TPAN-OPT/CO-WORKER

把可审计的 AI-agent 工作流编译成带 gate、审批、证据链和多 harness 资产的目标仓库文件。

TPAN-OPT/CO-WORKER 不是 agent 框架，而是包在 agent 工作外面的治理层：谁负责哪个阶段，哪些检查必须通过，审批证据在哪里，下一张工单卡在什么地方。它可以输出给 Claude Code、Codex、Cursor、OpenCode、CI、本地脚本和 MCP 工具使用。

English docs: README.md. 长版参考: docs/REFERENCE.zh-CN.md。

快速开始

对目标仓库运行已发布的 npm 包：

npx -y tpan-opt-co-worker quickstart --out /path/to/target-repo --name my-workflow

Quickstart 会写入 opt.workflow.json，编译 harness 资产，先跑一个 guardrail 证明，再默认运行离线 demo。离线 demo 只生成占位产物，用来预览路由和审批，不会把它包装成真实 agent 工作。

打开生成的 console：

open /path/to/target-repo/.tpan-opt-co-worker/console/index.html

需要自动刷新和浏览器审批时启动 live server：

npx -y tpan-opt-co-worker serve --out /path/to/target-repo

审批人不在本机旁边时，可加 --notify-webhook <url>，并在浏览器入口不是 localhost 时加 --public-url <url>，通知里会带签名审批链接。

审批人工 gate：

npx -y tpan-opt-co-worker approve human_approval \
  --stage ship \
  --by [email protected] \
  --out /path/to/target-repo

查看状态和下一张工单：

npx -y tpan-opt-co-worker status --out /path/to/target-repo
npx -y tpan-opt-co-worker next --out /path/to/target-repo

真实 Agent 运行

需要已安装的 agent CLI 产出真实文件时，加 --real：

tpan-opt-co-worker quickstart --out . --real --task "实现这次请求的变更" --force

也可以直接驱动已编译的 workflow：

node scripts/orchestrate-workflow.mjs --run-id real --invoke --loop \
  --task "实现这次请求的变更" \
  --agent-command 'codex exec --full-auto "Task: {task}. Use {brief}. Write {artifact}."'

如果请求的 agent 不在 PATH，quickstart 会回退到离线 demo，并明确说明。 真实 agent 产物会按 run id 隔离在 .tpan-opt-co-worker/artifacts/<run-id>/<stage>.md。

会生成什么

compile 会向目标仓库写入一组小而完整的操作面：

• AGENTS.md、CLAUDE.md、.codex/config.toml、Cursor rule、opencode.json
• .claude/agents/、.codex/agents/、.opencode/agents/ 下的按角色文件
• scripts/verify-workflow.mjs、run-workflow.mjs、orchestrate-workflow.mjs、list-runs.mjs
• .tpan-opt-co-worker/console/index.html 和 run/orchestration JSON 镜像
• GitHub Actions、GitLab CI、PR 模板、issue 模板
• CHANGELOG.md、CONTRIBUTING.md、.tpan-opt-co-worker/badges.md

直接编译：

npx -y tpan-opt-co-worker compile \
  --workflow /path/to/target-repo/opt.workflow.json \
  --out /path/to/target-repo \
  --force

Workflow 形状

最小 opt.workflow.json：

{
  "name": "production-feature-workflow",
  "version": "1.0.0",
  "roles": {
    "planner": {
      "skills": ["product-capability"],
      "permissions": ["read_repo", "write_docs"]
    },
    "engineer": {
      "skills": ["tdd-workflow"],
      "permissions": ["read_repo", "write_code", "run_tests"]
    }
  },
  "stages": [
    {
      "id": "clarify",
      "owner": "planner",
      "gates": ["scope_confirmed"]
    },
    {
      "id": "implement",
      "owner": "engineer",
      "gates": [
        { "id": "tests_pass", "type": "command", "command": "npm test" },
        { "id": "human_approval", "type": "manual" }
      ]
    }
  ]
}

Workflow version 必须遵循 SemVer。详见 docs/VERSIONING.md。

命令

tpan-opt-co-worker quickstart --out . [--template opt-demo] [--name my-workflow] [--task "要做什么"] [--real] [--no-demo] [--force]
tpan-opt-co-worker wizard --out . [--force]
tpan-opt-co-worker init --out . [--template production-feature] [--name production-feature-workflow] [--force]
tpan-opt-co-worker validate --workflow opt.workflow.json [--json]
tpan-opt-co-worker schema [--out workflow.schema.json] [--force]
tpan-opt-co-worker catalog [--kind presets|templates|policies|teams|marketplace] [--json] [--out catalog.json] [--force]
tpan-opt-co-worker compile --workflow opt.workflow.json --out . [--harness claude|codex|cursor|opencode|team] [--preset-file gate-presets.json] [--force] [--dry-run]
tpan-opt-co-worker status [--out .] [--run-id <id>]
tpan-opt-co-worker next [--out .] [--run-id <id>] [--task "要做什么"]
tpan-opt-co-worker dashboard [--out .]
tpan-opt-co-worker approve <gate> --by <approver> [--stage <stage>] [--note <text>] [--out .] [--run-id local]
tpan-opt-co-worker serve [--out .] [--port 4318] [--host 127.0.0.1] [--notify-webhook <url>] [--public-url <url>] [--no-open]
tpan-opt-co-worker mcp

MCP

Codex 配置：

[mcp_servers.co-worker]
command = "npx"
args = ["-y", "tpan-opt-co-worker", "mcp"]

Claude Desktop 风格配置：

{
  "mcpServers": {
    "co-worker": {
      "command": "npx",
      "args": ["-y", "tpan-opt-co-worker", "mcp"]
    }
  }
}

工具包括 co_worker_quickstart、co_worker_compile、co_worker_validate、co_worker_catalog、co_worker_status、co_worker_next、co_worker_approve。

当前实现范围

今天已经可用：

• workflow 校验、schema 输出、catalog 发现、preset 加载
• Claude Code、Codex、Cursor、OpenCode、CI、本地脚本、MCP、team playbook 的 harness 生成
• command gate、人工审批、运行证据、checkpoint/resume、live console 审批、serve 安全校验
• 离线 quickstart demo，以及显式 opt-in 的真实 agent 调用

边界：

• 默认 demo 是占位预览，不是真实 agent 产出
• 生成物是目标仓库中的文件，不是 SaaS 控制面
• 远程发布、push、第三方资源修改仍然由 operator 显式控制

更多细节见 docs/REFERENCE.zh-CN.md、docs/HERO-DEMO.md、docs/POSITIONING.md。

开发

node --test
node scripts/verify.mjs

发布检查包括 lint、typecheck、repo health、coverage、build smoke、pack smoke 和 npm audit --audit-level=high。

发布

通过 tag 发布，保证 README 里的 npx 示例对应当前 npm 包：

npm version patch
git push --follow-tags

GitHub Actions 的 Release workflow 会运行 npm run release:preflight，再使用 NPM_TOKEN 带 provenance 发布 tagged 版本到 npm。

License

MIT