claude-factory

由语音对话驱动的个人“循环工程”系统。

通过 Claude 应用的语音模式与之对话，后台的 Claude Code 会在仓库中工作，当需要判断时就会把问题抛回来。你用语音或画面回答后，工作就会继续。企划见 docs/01_企画書.md，实现方针见 docs/02_制作指示書.md，会话管理见 docs/03_セッション管理.md。

あなた（音声）
  └ Claude アプリ／ボイスモード（秘書）
      └ カスタムコネクタ = MCP Bridge Server（Bearer 認証）
          ├ Orchestrator ── Claude Code（claude-agent-sdk）── 各リポジトリ
          └ SQLite ── Dashboard（FastAPI + React）

核心是 计划 → 批准 → 执行 的门禁。任何会产生写入操作的工作，都会先以计划的形式返回来，在你批准之前绝不会执行。

1. 环境搭建

需要 Python 3.12 及以上、Node.js 18 及以上、Claude Code CLI（已用 Max 账户登录）。

# Mac / Linux
uv sync --extra dev              # または: pip install -r requirements.txt
cp .env.example .env
python -c "import secrets; print(secrets.token_urlsafe(32))"   # → .env の CF_MCP_TOKEN
python -c "import secrets; print(secrets.token_urlsafe(16))"   # → .env の CF_DASHBOARD_PASSWORD

# Windows
python -m venv .venv; .\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
copy .env.example .env    # 中身のトークンを実値に置き換える

Claude Code 的认证由 SDK 接管，所以请在执行主机上先启动一次 claude，并用 Max 账户登录。

让 config.yaml 适配自己的环境

至少要把允许操作的目录改掉。不在这里的所有路径都会被拒绝。

security:
  repo_allowlist:
    - ~/Private_Project           # Mac
    # - C:\Users\<you>\repos      # Windows

Related MCP server: MCP-Claude Code Bridge

2. 启动

./scripts/run_mcp.sh          # MCP サーバー（秘書の窓口 + ジョブのワーカー）
./scripts/run_dashboard.sh    # ダッシュボード（初回はフロントも自動ビルド）

.\scripts\run_mcp.ps1
.\scripts\run_dashboard.ps1

• MCP: http://127.0.0.1:8010/mcp

• 控制台: http://127.0.0.1:8787

真正执行作业的是 MCP 服务器进程。即使只启动控制台，队列也不会推进。需要常驻运行的是 run_mcp。

连通性确认：

curl -i http://127.0.0.1:8010/mcp                    # 401 = 認証が効いている
curl -s -X POST http://127.0.0.1:8010/mcp \
  -H "Authorization: Bearer $CF_MCP_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

3. 注册为连接器

./scripts/tunnel.sh quick     # 使い捨て（URL は起動ごとに変わる）

在显示的 https://<ランダム>.trycloudflare.com 末尾加上 /mcp，然后粘贴到 Claude 应用的“＋”→ 连接器 → 添加自定义连接器。

令牌的传递方式有两种：

路径方式因为令牌会出现在 URL 中而更容易泄露（会留在日志里）。如果可以使用请求头，就把 config.yaml 中的 mcp.allow_path_token 设为 false 来堵住。

4. 用法

对秘书（语音）可以这样说，比如：

了解情况

• “现在怎么样了？” → get_org_status（一次获取整个组织的情况。先用它）

• “那个工作呢？” → get_job（通过 detail 在 summary / report / log 之间切换）

• “读一下调查结果” → read_board（各部门产出的成果都会显示在这里）

推动组织（按影响的轻重）

• “用‘发票解析器’开始一个新任务” → create_task（一步完成创建目录 + git init + 注册。无需编辑 config.yaml，也无需重启）

• “把存储方式交给设计班讨论” → start_council（不会修改任何文件，可以放心使用）

• “会议结论是什么？” → get_council（结论、各议题的讨论、仍保留的反对意见）

• “请 demo 修复测试失败” → dispatch_to_code（只会生成计划）

• “批准” → answer_question（到这一步才会真正执行）

• “按这个目标交给你” → grant_mandate（开始自主运行。用 revoke_mandate 停止）

会话

• “把当前会话分叉，试试另一种做法” → fork_session（用 git worktree 隔离）

组织的形态（设计书 docs/04_組織化設計書.md）

子会社 = プロジェクト（互いに不干渉）
  部署 = 役割        調査 / 設計班 / 実装 / デザイン / 統合管理
    成果ボード       部署はここだけを介して成果を見せ合う

设计班的会议由主持人主导，分 4 个阶段进行。

1. 预读 — 主持人自己解决显而易见的问题（记录到 resolved_by_chair），只提炼出争议点

2. 交议 — 针对每个争议点，从成员名册中指定人选（附理由）

3. 讨论 — 被指定的人陈述自己的意见，以及对先前意见的批评

4. 结论 — 主持人给出每个争议点的结论、仍保留的反对意见、以及需要人类处理的论点

名册见 config/personas.yaml（主持人 1 名 + 成员 10 名）。可以自由编辑，启动时自动生效。

各部署的权限（最小权限）

已将“调研可以访问 Web 但不能写文件”“实现可以写文件但不能访问 Web”分离开。修改请在 config.yaml 的 roles: 中进行，只有人才能修改（不为综合管理代理留出扩大自身权限的路径）。

自主运行（委任状）

用 grant_mandate 按目标批准后，综合管理会把工作分派给各部署，无需逐项批准即可推进。作为减少批准的对价，它以随时可以丢弃的形式运行。

• 创建专用工作分支（不让碰 main）

• 设置预算（作业数・成本）和期限，用完后自动停止

• 删除、git push、修改历史、添加依赖都不在委任范围内。遇到这些必须停下来确认

• 可以用控制台的“停止”按钮（revoke_mandate）连同执行中的作业一起撤销

控制台中可以看到：待处理问题队列、进度时间线、实时日志、报告、会话分叉树、审计日志。回复无论通过语音还是画面，都走同一条路径。

秘书的技能（skills/）

由于每天早上都会开启新聊天的运行方式，秘书没有前一天的记忆。启动步骤以技能的形式放在 skills/factory-startup/（情况收集 → 朗读顺序 → 今日建议，附朗读脚本）。请从 Claude 应用的设置中上传，然后在聊天开头输入 /factory-startup（缩写 /cf）来调用。没有设置自然语言触发词（为了避免误触发和漏调用）。应用的 / 建议来自技能的 name，所以名称本身就是信号。详见 skills/README.md。

连接器侧的 SECRETARY_GUIDE（附加到每次请求＝保持简短）与技能（只在需要时读取＝放置步骤和脚本）分工明确。

对秘书有效的指示（企划 §验证4）

为了防止秘书在对话途中擅自发出请求，可以这样对秘书说：

在我说“就按这个去请求”之前，不要调用 dispatch_to_code。 在那之前请陪我商量，一起把指示文整理好。

5. 安全（制作指示书 §8）

已实现的防御：

在实际 Claude Code 中试用后发现两个需要注意的点，已做好对策：

• can_use_tool 不会被 CLI 自动批准的工具调用。 如果只依赖授权回调，即使在计划模式下也会发生仓库外写入。为此，已将 disallowed_tools 的 CLI 级禁止与 OS 沙盒（orchestrator.sandbox）叠加使用。

• 通过 cd 逃逸目录是路径检查无法阻止的。 使用 _bash_escapes_workspace 检查 Bash 命令中的绝对路径和 ..。

• 目标仓库的 .claude/settings.json 不加载（setting_sources=[]）。如果加载，仓库就能自我批准自己的权限。

6. 固定公开（M5）

一次性隧道的 URL 在每次启动时都会改变，因此若要长期使用，请改为命名隧道。

cloudflared tunnel login
cloudflared tunnel create claude-factory
cloudflared tunnel route dns claude-factory mcp.<domain>
cloudflared tunnel route dns claude-factory dash.<domain>

~/.cloudflared/config.yml：

tunnel: claude-factory
credentials-file: /path/to/<tunnel-id>.json
ingress:
  - hostname: mcp.<domain>
    service: http://localhost:8010
  - hostname: dash.<domain>
    service: http://localhost:8787
  - service: http_status:404

长期公开由 systemd 的 cloudflared.service 负责（读取 /etc/cloudflared/config.yml）。

systemctl status cloudflared          # 状態確認
sudo systemctl restart cloudflared    # 設定変更の反映
journalctl -u cloudflared -f          # ログ

也可以通过 ./scripts/tunnel.sh named claude-factory 启动，但因为会在与常驻服务相同的隧道上重复建立连接器，所以通常不使用。如需切换为手动运行，请先执行 sudo systemctl stop cloudflared。脚本侧在检测到常驻服务时也会发出警告，并请求确认。

Route 53 这边由 cloudflared tunnel route dns 创建 CNAME（<tunnel-id>.cfargotunnel.com）。连接器注册 URL 为 https://mcp.<domain>/mcp。控制台前面放置 Cloudflare Access，只有在这种情况下才采用 dashboard.auth: none。

7. 开发

.venv/bin/python -m pytest -q                                  # テスト
cd src/claude_factory/dashboard/web && npm run dev             # フロントの開発サーバー

结构与制作指示书 §2 对应（没有直接放在 src/ 下，而是做成了 src/claude_factory/ 包）：

src/claude_factory/
├─ config.py        設定（config.yaml + .env）
├─ models.py        型・出力規約・その解析
├─ store.py         SQLite DAO
├─ security.py      トークン・allowlist・レート制限
├─ runner.py        claude-agent-sdk ラッパと承認ゲート（役割別の権限）
├─ orchestrator.py  ジョブキュー、計画→承認→実行、自走ループ
├─ sessions.py      セッション一覧/閲覧/分岐（git worktree 隔離）
├─ personas.py      社員名簿と組閣
├─ council.py       設計班の合議エンジン
├─ integrate.py     統合管理（作業計画を出すだけ。実行はしない）
├─ org.py           組織全体の状況
├─ mcp_server.py    秘書向け MCP
└─ dashboard/       FastAPI + React(Vite)

文档：docs/01_企画書.md（构想）→ 02_制作指示書.md（基础）→ 03_セッション管理.md（补充）→ 04_組織化設計書.md（组织化）。

8. 剩余事项

• M6 语音 E2E：用语音仅凭对话跑通一个真实项目（连接器注册后手动确认）。

• 等待判断的推送通知（v2）。

• 分叉 worktree 的清理规则（合并后删除还是保留）。

• 检测综合管理反复派发同一工作的情况（目前预算和期限是唯一的制约）。

• 部署之间意见不一致时，调解者是交给综合管理，还是上报给人。