mancode

目录

• mancode 是什么？
• 为什么使用 mancode？
• 安装方法
• 使用方法
• 跨会话继续工作
• 团队协作
• 工作原理
• CLI 参考
• 隐私和安全
• 故障排查
• 常见问题
• 仍在推进

mancode 是什么？

mancode 是一个 AI 编码代理工作流调度工具。它给 agent 不同强度的工作模式： 日常任务用轻量 solo，关键任务用季后赛级别的 /man，复杂任务让教练组 subagents 负责调研、计划、实现和审查。

**mancode Continuity（跨会话与团队协作运行时）**负责把任务、决策和验证证据安全地 带到后续对话，并协调多人或多 Agent 的任务权威。

mancode 会安装三类能力：

1. 工作流权威数据：管理显式 session、TaskRef、Context Pack、workflow 和团队协调。
2. Skills / modes：提供 solo、/manba、/man、/manteam、/manps、 /mansolo 工作流模式。
3. 平台 bootstrap：把原入口接到 mancode；只有 --legacy 才安装旧 hooks。

每个受支持平台继续使用原来的 man* 入口，并通过静态 bootstrap 接入统一的 Context Pack 与 workflow authority。当 AI 编码代理写太多代码、忽略已有 UI 系统、 跳过计划，或者关键改动需要稳定工程流程时，mancode 可以作为一层本地工作流约束。

mancode 不是 Claude Code、Cursor、Codex 或 Copilot 的替代品。它是在现有 agent 上加的一层工作流：提供上下文、模式切换和审查纪律。

为什么使用 mancode？

• 减少 AI 过度设计：先复用已有代码、标准库、已安装依赖和一行修复，再考虑新增抽象。
• 在存在 UI 时匹配现有设计系统：检查项目 UI 依赖、Tailwind 配置、CSS 变量和已有组件，让 agent 复用现有颜色、字体和交互模式。
• 先把需求和计划对齐：/man 会调研项目、引导澄清会改变方案的需求、推荐可行选项并生成可确认的持久计划；计划完成后不会自动进入完整实施。
• 自由选择执行强度：计划确认后，可只保留计划、交给默认 solo 轻量开发，或继续完整 /man 的验证与有界风险审查。
• 保留工作流产物：调研、计划、审查报告和总结会保存到 .mancode/<namespace>/workflows/<ULID>/。
• 支持团队上下文：/manteam 通过 .mancode/shared/ 的类型化实体共享已确认信息。
• 扫描项目健康度：mancode manps 检测陈旧 TODO、未使用依赖、风险依赖、混用图标系统和硬编码设计值。

前后对比

没有 mancode 时，像“添加退出登录按钮”这样的请求，AI 可能会新建组件、新建样式文件、 新增颜色变量。

使用 mancode 后，agent 会看到你项目里已有的 Button 组件和设计 token：

<Button variant="default" onClick={handleLogout}>
  退出登录
</Button>

默认工作流会在写代码前推动 agent 思考六个问题：

1. 这个改动解决什么问题？
2. 能否复用已有实现？
3. 最小可行改动是什么？
4. 能否不拆新系统？
5. 非平凡逻辑怎样做最小运行验证？
6. 有什么没把握的（先自查，仍不确定再问用户）？

适合什么项目？

• 正在使用 AI 编码代理的后端、Web、移动端、桌面端、CLI、库、数据或混合项目
• 希望在原 man* 命令中使用 Context Pack、skills 和显式治理的用户
• 希望 AI 代理复用已有组件和代码模式的团队
• 需要可重复 AI 辅助代码审查流程的项目
• 已有 UI 组件、主题、CSS 变量或设计约定的界面项目
• 希望保留本地团队记忆、但不希望引入遥测的团队

针对最新模型审查能力的优化

新的推理模型往往自带较强自审倾向，较小模型则可能在没有明确要求时很少审查。mancode 同时考虑了这两种行为：

• solo 保持轻量：只对本次 diff 做一次受限自检，运行最窄的有效验证，不调用额外 reviewer，也不开 review 循环。
• /man 对普通治理任务执行一次定向质量审查；鉴权、支付、敏感数据、迁移、公开 API、未可信输入、并发或基础设施等硬风险才执行质量 + 安全完整审查。
• finding 必须有改动行证据和用户影响。workflow CLI 会记录所需审查领域和 blocker，只允许一轮修复；审查未完成或 blocker 未清零时不能完成任务。

这样既不会让强模型一直 review，也不会因为弱模型不主动审查而降低任务质量。

安装方法

状态：mancode Continuity v0.6.2。Claude Code、Cursor、ChatGPT 桌面端中的 Codex、Codex CLI、GitHub Copilot、ZCode、Kimi Code、Qoder 和 DeepSeek Harness adapter 均已接入。

需要 Node.js 22 或更高版本。原生支持 macOS、Linux、Windows CMD、 PowerShell 和 Git Bash。Git 是可选依赖：未安装时仍可初始化，只会把团队 自动检测安全降级为 solo。Claude Code hooks 由 Node 执行，不需要 Bash 或 jq。

先通过 npm 全局安装，进入你的项目目录，然后运行初始化命令：

npm install -g mancode
cd your-project
mancode init                      # 交互式选择平台
mancode init --platform cursor    # 或显式指定一个/多个平台
mancode init --platform codex,cursor
mancode init --platform all

init 会引导选择 Agent，并把检测到的 Agent 仅作为提示；不会悄悄安装全部适配器。 可以选择一个、多个或“全部平台”。Git 不是初始化前提；已有 manifest、顶层源码文件或 常见源码目录的项目可直接初始化。全新空目录会询问是否初始化为通用项目，因此用户不必 先知道 git init 或 npm init -y。之后再加入 Git 或项目源码也安全，执行 mancode refresh-project 即可刷新项目事实和已安装的静态适配器。

初始化后，继续正常使用你的编码代理。solo 默认自动生效：日常训练，零仪式感。遇到需要 计划、测试和多 agent 审查的任务时，使用 /man：季后赛，每球必争。

平台支持

• Claude Code：隐藏 bootstrap 与原 mode skills；默认不依赖 hooks
• Cursor：.cursor/rules/*.mdc bootstrap 与 .cursor/commands/ 原 mode commands
• Codex（ChatGPT 桌面端、CLI、IDE 扩展）：托管 AGENTS.md block，并在 .agents/skills/ 下提供 $man* 项目 skills
• GitHub Copilot：托管 instruction block 与 .github/prompts/ 原 mode prompts
• ZCode：托管 AGENTS.md block，并暂按 .agents/skills/ 生成 $man* skills；项目级 skill 发现和 slash commands 仍需确认 workspace 路径后再发布承诺
• Kimi Code（桌面端、CLI）：托管 AGENTS.md block，并在 .agents/skills/ 下提供 /skill:man* 项目 skills；宿主发现路径仍需真实验证
• Qoder（IDE、CLI）：托管 AGENTS.md block，并在 .qoder/commands/ 下提供 /man* 项目 commands；宿主发现路径仍需真实验证
• DeepSeek Harness：托管独立的 AGENTS.md block，并在优先级更高且与其他 agent 隔离的 .dsh/skills/ 下提供用户显式 /man* skills；官方文件发现契约已确认， GUI 发现、双窗口 session 和 subagent 传播仍需真实宿主验证
• Windsurf、Cline、Roo Code：后续计划

安装参数

mancode init --yes        # 跳过通用项目确认（CI 中仍需 --platform）
mancode init --team       # 强制启用团队模式
mancode init --no-team    # 强制禁用团队模式
mancode init --platform PLATFORMS # 一个或多个：claude-code,cursor,codex,copilot,zcode,kimi-code,qoder,dsh，或 all
mancode init --empty      # 非交互脚本中允许安全的空目录
mancode init --lang zh-CN # 显式指定初始化语言（zh-CN 或 en）
mancode init --legacy --force # 仅 legacy：重装旧 state/hook 架构
mancode init --legacy --style NAME # 仅 legacy：保存默认审美偏好
mancode refresh-project   # 后续加入 Git 或项目文件后刷新项目事实
mancode adapter status --json # 检查实际 managed content digest
mancode adapter upgrade --platform codex --dry-run # 只生成 staging 预览
mancode adapter upgrade --platform codex --confirm --operation-id <operationId> --session <id> --client <client>

安装后创建哪些文件？

默认的 mancode init 会创建 mancode 工作流目录和平台适配文件：

.mancode/
├── schema.json
├── shared/config.json
├── shared/context/project.json
├── shared/context/design-policy.json # 可选：design configure 后创建
├── shared/team/
└── local/                         # session、workflow、扫描报告和样式缓存

.claude/skills/                  # Claude Code：bootstrap + 原 mode skills
.cursor/rules/ + commands/       # Cursor：bootstrap + 原 mode commands
AGENTS.md                        # Codex / ZCode / Kimi Code / Qoder / DeepSeek Harness：各自托管 instructions block
.agents/skills/                  # Codex / ZCode / Kimi Code：原 mode skills
.qoder/commands/                 # Qoder：原 mode commands
.dsh/skills/                     # DeepSeek Harness：用户显式原 mode skills
.github/copilot-instructions.md  # GitHub Copilot：托管 instruction block
.github/prompts/                 # GitHub Copilot：原 mode prompts

.mancode/ 把可共享的工作流数据与 checkout-local 的 session、workflow 和扫描报告分开。 平台文件只保存 bootstrap 和原模式入口，不保存 task/session 副本。 mancode init --legacy 才会创建旧的 state.json 布局。

使用方法

mancode 不把“当前模式”写进持久状态。需要某种工作方式时，直接在 AI 编码代理的 对话中调用原命令；入口会解析 status、session、TaskRef 和 Context Pack：

各界面的调用方式

Claude Code 和 Cursor 使用 /man、/manba 等命令；ChatGPT 桌面端、Codex CLI 和 Codex IDE 扩展会从 .agents/skills/ 读取项目 skill，其中 $man、$manba 等 $ mention 是跨界面稳定的显式调用方式。ChatGPT 桌面端还会把已启用的 skill 显示在 slash command 列表，因此发现并启用 man 后可从列表中选择 /man；CLI/IDE 则使用 $man 或 /skills。这些属于 agent skills，而不是已弃用的 custom prompts。参见官方 skills 文档 和 slash command 文档。 已有 workflow 元数据继续兼容，不需要迁移。

DeepSeek Harness 从 .dsh/skills/ 发现入口，使用 /man、/manba 等名称显式调用。 这些 skill 被标记为仅用户调用，不会让宿主自动切换 mancode mode。

# Claude Code / Cursor
/manba                     # 定位 bug 并验证真实用户路径
/man                       # 完整 9 步流程和有界风险审查
/manps                     # 项目健康检查
/manteam                   # 团队模式和共享记忆
/mansolo                   # 回到 solo 模式

# ChatGPT 桌面端 Codex / Codex CLI / IDE
$manba
$man
$manps
$manteam
$mansolo

# DeepSeek Harness
/manba
/man
/manps
/manteam
/mansolo

/man 如何工作：季后赛模式

/man 既是正式计划入口，也是面向关键任务的季后赛模式。即使当前处于默认 solo，当用户要求先调研、给方案或出计划时，也会进入 /man。它会先了解项目， 只追问会改变范围、架构、成本或验收的问题；需求足够清晰时不制造形式问题，需求 不清晰时会停下等待用户回答；适合由系统推荐的决策会给出 2–3 个 方案、优缺点和明确建议。需求足够清楚后，计划才会写入 .mancode/local/workflows/<ULID>/plan.md。

计划完成不会自动开始完整开发。用户在计划关卡选择：交给 solo 按已确认计划 轻量开发、继续完整 /man、只保留计划，或修改计划。只有选择完整 /man 才继续 后续实施、验证和风险审查：

1. 球探报告：梳理既有代码、风险和未知项。
2. 需求澄清：按需求就绪程度引导对齐；问出所有会改变方案且无法从项目查清的疑问，可按需分多批，不限制数量、不重复已确认内容，有合适方案时直接给出推荐。
3. 计划：Plan Coach 先检查输入是否完整，再输出包含技术选择、边界和验收标准的持久计划。
4. 计划关卡：选择 solo 轻量执行、完整 /man、只保留计划或修改计划。
5. 实施：Head Coach 按确认计划实现。
6. 验证与审查范围：运行 build、lint、test、smoke test，再根据实际 diff 和硬风险选择定向或完整审查。
7. 录像分析 1：只对改动行为做有证据的质量审查。
8. 录像分析 2：仅完整审查任务执行安全与边界审查，并抑制相同根因的重复评论。
9. 收尾：一轮 blocker 修复、不重复 reviewer 的最终复验、summary、workflow 状态和 memory 更新。

跳过的步骤会被记录。所有产物保留在本地，之后可以回看当时为什么做某个决策。

默认 solo 也执行同一个轻量清晰度判断：清晰、窄范围的需求直接做最小改动；会改变 行为、范围、验收或关键约束的歧义必须先提问。涉及架构、owner/source of truth、迁移、 跨模块或团队决策时，solo 推荐 /man，但不会自行切换模式。

跨会话继续工作

mancode 把目标、需求、计划、检查结果和交接信息保存在稳定 TaskRef 下。换一个聊天 窗口、重启编码