OpenCode Feishu Progress Reporter

这个仓库提供一套仓库级 Feishu 进度同步方案，覆盖 OpenCode skill、GitHub Copilot CLI MCP tool 和 Claude Code 项目配置，目标是把 AI 工作进度持续写入飞书多维表格，形成可追踪、可筛选、可审计的流水记录。

下面这张图是脚本自动生成并上传到飞书多维表 附件 字段的 PNG 预览示例：

请阅读 https://cnb.cool/asahiluna/opencode-feishu/-/git/raw/main/docs/AI-INSTALL.md 并按文档完成安装。

详细安装说明、全局命令 cf 的安装方式，以及“交互式 AI 必须先向用户索要哪些信息、安装时必须把 Copilot MCP 配置写入 ~/.copilot/mcp-config.json、安装完成后必须如何向用户交付使用方法”都集中放在 docs/AI-INSTALL.md。

补充说明：这个插件的一部分能力依赖当前仓库的 git 提交历史来生成更准确的进度信息；同时，这套工作流默认允许 AI 在仓库里自动提交、自动推送。因此更推荐把 AI 工作放在独立的 git worktree 里运行，避免和你手头正在编辑的工作区互相干扰。多 AI 终端（含 tmux 命名规范、worktree 新建/同步标准口令）请直接使用 docs/WORKTREE-AI-PLAYBOOK.md。

安装归档现在会由 CI 发布到专用的 install-archive 分支，而不是反复回写 main。这样可以保留“直接下载归档安装”的体验，同时避免二进制归档频繁干扰主分支提交和 rebase。

安装完成后，AI 应该明确告诉用户：

• 在任意目录直接运行 cf 启动 Copilot CLI，并保留当前目录作为工作目录
• cf 启动时会把仓库内置的 AGENTS.md 与 .github/copilot-instructions.md 同步到当前目录；如果目标文件已存在，则在末尾追加受管内容而不覆盖原文件
• 在任意目录直接运行 feishu-copilot，并保留当前目录作为工作目录
• 在任意目录直接运行 feishu-opencode
• 在任意目录直接运行 feishu-claude

另外，cf 现在会在退出时检查当前项目的 git 状态；如果这次 session 里发生了代码变更，但没有产生 Feishu 上报，或者最后一次上报不是 done / blocked，它会给出强警告并以非零状态退出。

如果你现在想先收敛功能，只保留“把规则文件放到正确位置即可生效”的能力，可以直接用：

./scripts/setup-feishu-progress.sh sync-managed-md --engine all --scope project --target "$PWD"

这会把仓库里的 Markdown 规则文件同步到当前项目对应位置：

• Copilot：AGENTS.md、.github/copilot-instructions.md
• OpenCode：AGENTS.md、.opencode/skills/feishu-progress-reporter/SKILL.md
• Claude：.claude/CLAUDE.md

如果你要做全局生效，用：

./scripts/setup-feishu-progress.sh sync-managed-md --engine all --scope global

它会同步到这些全局位置：

• Copilot：~/.copilot/copilot-instructions.md
• OpenCode：~/.config/opencode/AGENTS.md、~/.config/opencode/skills/feishu-progress-reporter/SKILL.md
• Claude：~/.claude/CLAUDE.md

这个命令只负责规则/技能 Markdown 的落位，不会自动安装 Feishu .env、MCP 配置、渲染依赖或全局启动命令。如果你需要真正把进度写入飞书，仍然要继续完成完整安装流程。

• AGENTS.md：把“有进度就记一条”设成项目默认规则
• .github/copilot-instructions.md：GitHub Copilot CLI 原生仓库指令
• .claude/CLAUDE.md：Claude Code 项目级仓库指令
• .mcp.json：Claude Code 项目级 MCP 配置
• .opencode/skills/feishu-progress-reporter/SKILL.md：skill 说明和调用规范
• .opencode/skills/feishu-progress-reporter/scripts/report_progress.py：写入飞书多维表格的脚本
• .opencode/skills/feishu-progress-reporter/scripts/init_progress_table.py：初始化推荐表结构
• .opencode/skills/feishu-progress-reporter/scripts/feishu_progress_mcp.py：给 Copilot CLI 用的 MCP progress tool
• .opencode/skills/feishu-progress-reporter/.env.example：本地环境变量模板
• .copilot/scripts/start-feishu-mcp.sh：供用户级 ~/.copilot/mcp-config.json 调用的仓库内 MCP 启动器
• scripts/setup-feishu-progress.sh：统一的安装、自检、Markdown 规则同步入口
• docs/AI-INSTALL.md：给 AI 执行安装时看的单独说明文档
• docs/opencode-feishu-template.tar.gz：安装归档产物，会由 CI 发布到 install-archive 分支供直装流程下载
• scripts/start-copilot.sh：推荐启动入口
• scripts/install-agency-agents.sh：为 OpenCode 试点安装 agency-agents（默认 pin 到 commit SHA）
• docs/AGENCY-AGENTS-INTEGRATION.md：agency-agents 接入、测试与回滚说明
• docs/K2P5-AGENCY-HYBRID-PROMPTS.md：oh-my-opencode + K2.5 + agency-agents 混合提示词模板

如果你想验证“角色化专家 agents”是否能提升复杂任务交付质量，可以在当前仓库做可回滚试点：

./scripts/setup-feishu-progress.sh install-agency-agents --profile core
./scripts/start-agent.sh opencode-agency

说明：

• core profile 会安装一小批 OpenCode agents 到 .opencode/agents/，便于先做小样本验证。
• 现有强约束不变：AGENTS.md + feishu-progress-reporter 的阶段上报与 done/blocked 收尾仍必须执行。
• 详细策略见 docs/AGENCY-AGENTS-INTEGRATION.md。

如果你使用的是 oh-my-opencode + K2.5，推荐直接套用混合协议：

先用 K2.5 子代理做拆解与并行检索，再用 1 个 agency 角色做领域实现，最后用 momus 复核。

完整模板见 docs/K2P5-AGENCY-HYBRID-PROMPTS.md。

为了稳定、低维护、兼容脚本直接写入，建议第一版表结构以“文本字段为主”，不要一上来依赖复杂公式或关联字段。

推荐表名：AI工作进度

推荐字段如下：

这个设计的重点不是“看起来漂亮”，而是“稳定可写、后续好筛选”：

• 记录时间 用本地时间加时区标注，优先保证人直接阅读时不需要自己换算时区
• 进度摘要 + 当前阶段 + 状态 是最关键的三元组
• 其余字段用于后期按项目、会话、仓库、模型过滤
• 会话用量 会把当前任务阶段能拿到的 token / 上下文窗口摘要直接写到表里
• 原始载荷 让排错更直接，特别适合第一版联调
• 同一 任务ID 会更新同一条记录，便于在飞书里持续跟踪一个任务

除了让 AI 持续写入多维表，实际使用时也建议你在飞书多维表里再配一个工作流或自动化：

• 触发条件可以选“当记录新增时”或“当记录更新时”
• 通知对象可以是个人、群聊，或者特定负责人
• 通知内容建议至少带上 任务标题、进度摘要、状态、记录时间，有需要的话再附上 附件 预览图链接

这样一来，AI 负责持续把进度写进表里，飞书负责在数据变化时主动提醒，不需要有人一直盯着多维表刷新。

你需要一个飞书自建应用，并拿到：

• FEISHU_APP_ID
• FEISHU_APP_SECRET
• FEISHU_BITABLE_APP_TOKEN
• FEISHU_BITABLE_TABLE_ID

脚本会先获取 tenant_access_token，然后调用飞书多维表格新增记录接口。

复制模板：

cp .opencode/skills/feishu-progress-reporter/.env.example .opencode/skills/feishu-progress-reporter/.env

然后填入真实值。.env 已加入 .gitignore，不会被提交。默认还支持：

• PROGRESS_LANGUAGE=zh-CN
• PROGRESS_TIMEZONE=Asia/Shanghai

如果你希望在其他电脑上也自动生成“真实 Markdown 截图预览”，而不是结构化降级图，再执行一次：

./scripts/setup-feishu-progress.sh install-renderer-deps

这个命令会在 .opencode/skills/feishu-progress-reporter/ 下执行 npm install，安装 Markdown 解析、纯 Node PNG 渲染和 Playwright 浏览器渲染所需依赖，并额外执行 npx playwright install chromium。依赖装好后，report_progress.py 会自动按策略链生成 PNG 预览。

渲染器现在会按多种方案顺序尝试，例如：

• resvg + 内置 Noto Sans SC 字体的纯 Node 文本渲染
• Playwright 自带 Chromium
• 已安装的系统 Chromium / Chrome / Edge
• 可选的完整 playwright 包（如果你自行安装）

只要其中任一方案可用，就会生成带文字的 PNG 预览；全部失败时才回退到结构化 PNG。

如果你希望仓库自己做安装引导和自检，直接运行：

./scripts/setup-feishu-progress.sh
./scripts/setup-feishu-progress.sh init-env
./scripts/setup-feishu-progress.sh install-renderer-deps
./scripts/setup-feishu-progress.sh install-copilot-mcp-config
./scripts/setup-feishu-progress.sh check --engine copilot
./scripts/setup-feishu-progress.sh check --engine opencode
./scripts/setup-feishu-progress.sh check --engine claude

这个脚本同时是“给人看”和“给 AI 看”的单一事实来源，里面明确写了：

• 要复制哪个 .env 模板
• Markdown 预览图依赖该如何安装
• 必填的飞书变量有哪些
• Copilot CLI 依赖哪些文件
• OpenCode 依赖哪些文件
• Copilot MCP 配置如何做真实握手探测

以后推荐让 Copilot 或 OpenCode 先读这个脚本，再开始安装或联调。

这个仓库同时支持：

• GitHub Copilot CLI
• OpenCode

两边共用同一套飞书配置、同一套 skill、同一套进度写入脚本。

最省事的方式是统一入口：

./scripts/start-agent.sh copilot

如果你只想走 Copilot，也可以继续使用专用脚本：

./scripts/start-copilot.sh

这个脚本会：

• 自动切到仓库根目录
• 使用用户级 ~/.copilot/mcp-config.json 中注册好的 feishu-progress
• 复用仓库内的 .copilot/scripts/start-feishu-mcp.sh 作为 MCP 启动器
• 在启动前执行一次仓库内自检，提前暴露 MCP 路径或配置问题

进入 Copilot CLI 之后，建议立即检查：

/instructions
/mcp

确认以下两类内容都已生效：

• AGENTS.md 和 .github/copilot-instructions.md
• MCP server feishu-progress

首条提示建议直接写：

Follow the repository instructions. Use the feishu-progress MCP tool at every meaningful milestone, blocker, validation step, and final handoff.

推荐流程：

1. 进入仓库目录
2. 首次安装时先运行 ./scripts/setup-feishu-progress.sh install-copilot-mcp-config
3. 运行 ./scripts/start-agent.sh copilot 或 ./scripts/start-copilot.sh
4. 在 CLI 内执行 /instructions 和 /mcp
5. 确认已加载：
   • AGENTS.md
   • .github/copilot-instructions.md
   • MCP server feishu-progress
6. 开始任务

在 Copilot CLI 里，优先使用 MCP 工具：

• init_progress_table
• report_progress

如果某次没有用到 MCP，仓库指令也要求它至少回退到脚本调用。

OpenCode 侧依赖的是仓库内 skill：

• .opencode/skills/feishu-progress-reporter/SKILL.md

同时我加了仓库级 opencode.json：

• 默认允许 feishu-progress-reporter 这个 skill 被调用

推荐流程：

1. 在仓库根目录启动 OpenCode
2. 推荐直接运行 ./scripts/start-agent.sh opencode
3. 确认它工作目录就在本仓库
4. 让模型显式使用 skill，例如：

Use the feishu-progress-reporter skill for this task and append one Feishu progress record at every milestone.

如果你希望它先建表，再开始工作，可以这样提示：

Use the feishu-progress-reporter skill. If the progress table is not initialized, initialize it first, then append a new record whenever progress changes.

OpenCode 主要走的是：

• AGENTS.md
• .opencode/skills/feishu-progress-reporter/SKILL.md
• opencode.json

它不像 Copilot CLI 一样依赖用户级 ~/.copilot/mcp-config.json，因此 OpenCode 侧重点是 skill + 规则文件。

现在仓库支持统一入口：

./scripts/start-agent.sh copilot
./scripts/start-agent.sh opencode

这个脚本会自动：

• 切到仓库根目录
• copilot 模式下依赖用户级 ~/.copilot/mcp-config.json
• opencode 模式下直接在仓库根目录启动，确保能发现 skill 和规则文件
• 在启动前执行对应的仓库自检，尽量把配置错误前置到启动阶段

python3 .opencode/skills/feishu-progress-reporter/scripts/report_progress.py \
  --phase "联调" \
  --status "working" \
  --summary "正在验证飞书写入链路" \
  --details "本次仅做 dry-run 验证" \
  --language "zh-CN" \
  --task-id "example-todo-id" \
  --code-snippet ".opencode/skills/feishu-progress-reporter/scripts/report_progress.py:573-680" \
  --conversation-prompt "请优化实现细节，避免重复解决方案，并对敏感信息做脱敏" \
  --attachment-paths "/tmp/proof.png" \
  --attachments "existing_file_token" \
  --dry-run

如果这条进度对应实际代码修改，调用方应主动传入至少一个 --code-snippet path:start-end。--code-snippet 用于在 Markdown 的 实现细节 里展示关键代码。若未提供代码片段，脚本会在同一 task_id 的首次写入时记录当时的最新 HEAD 作为任务基线；后续更新会回退到“该基线之后的所有 commits + 当前未提交改动”，并按 增加 / 修改 / 删除 分组生成带 diff 代码块的说明。为了让回退结果完整，建议在真正开始实现前先为该 task_id 写入一次进度，锁定任务基线；如果两者都不适合展示，就会直接省略 实现细节 章节，避免把 解决方案 原样复制一遍。

--conversation-prompt 会在文档末尾追加 交流提示（已脱敏） 小节，适合保留与你交流时的关键提示词，但会自动脱敏常见路径和凭据类字段。

如果 dry-run 输出无误，再去掉 --dry-run 进行真实写入。真实写入时，脚本会自动生成一份 Markdown 报告并上传到 进度Markdown 字段，同时还会自动生成至少一张 Markdown 预览 PNG 并上传到 附件 字段；--attachment-paths 仍可继续追加截图、图表或其它补充素材。

如果你已经有 FEISHU_APP_ID、FEISHU_APP_SECRET、FEISHU_BITABLE_APP_TOKEN，可以先初始化推荐表：

python3 .opencode/skills/feishu-progress-reporter/scripts/init_progress_table.py --dry-run

确认 dry-run 计划无误后，正式执行：

python3 .opencode/skills/feishu-progress-reporter/scripts/init_progress_table.py

脚本会：

• 在对应多维表格 app 下创建名为 AI工作进度 的数据表
• 自动添加推荐字段（包含 进度Markdown 和 附件 两个附件字段）
• 输出新建出来的 table_id

后续把这个 table_id 写回 .env 的 FEISHU_BITABLE_TABLE_ID，进度写入脚本就能直接用了。

如果你已经手工建好了数据表，也可以指定已有 table_id 补齐字段：

python3 .opencode/skills/feishu-progress-reporter/scripts/init_progress_table.py \
  --table-id "tblxxxxxxxx"

仓库已经提供两种路径：

如果你是通过 ./scripts/start-copilot.sh 启动的，Copilot CLI 会拿到一个原生工具：

• tool 名称：init_progress_table
• tool 名称：report_progress

这个工具比让模型拼 shell 命令更自然，也更容易被模型稳定调用。

如果某次 Copilot 没有使用 MCP tool，仓库指令仍要求它至少执行：

python3 .opencode/skills/feishu-progress-reporter/scripts/report_progress.py \
  --phase "实现中" \
  --status "working" \
  --summary "已完成核心逻辑" \
  --details "补充了文档和本地校验" \
  --language "zh-CN" \
  --task-id "core-logic" \
  --attachment-paths "/tmp/validation.png" \
  --attachments "existing_file_token"

如果你希望飞书里的同步内容默认使用某种语言，可以在 .opencode/skills/feishu-progress-reporter/.env 里设置：

PROGRESS_LANGUAGE=zh-CN

脚本会自动把常见的 status / phase 值本地化，并让生成的 Markdown 标题跟随该语言。对于 summary、details 这类自由文本，调用方也应直接使用同一语言填写；仓库内的 skill 和 Copilot 指令已经按这个约定更新。

先说结论：只靠提示词，无法做到绝对 100% 强制。

这个仓库现在做到了比较接近“强约束”的组合：

• 指令层：AGENTS.md + .github/copilot-instructions.md
• Skill 层：.opencode/skills/feishu-progress-reporter/SKILL.md
• 工具层：本地 MCP server，给 Copilot 一个显式的 init_progress_table / report_progress 工具
• OpenCode 配置层：opencode.json 明确允许 skill
• 启动层：scripts/start-copilot.sh + install-copilot-mcp-config 组合，确保 Copilot 走用户级 MCP 配置

这已经比单纯写一份 skill 稳很多。

如果你还想更硬一点，下一步可以做：

• 包一层你自己的启动器，只允许通过它启动 Copilot
• 对 Copilot 的会话日志做旁路审计，发现缺少进度记录就告警
• 在团队侧把这个仓库模板化，统一使用同一启动方式

This project is licensed under the MIT License. See LICENSE for details.