企业官网建设流程全解析

• 人工智能
• AI Agent
• Agent 编排
• AI 技能

导读

本文系统讲解 oh-my-opencode-slim 仓库中面向 AI 工程技能（engineering skills）的领域文档消费协议，即 docs/agents/domain.md 定义的全部规则：探索代码库前必须先读哪些文件、术语表词汇如何使用、缺失文档时如何静默降级、Triage 标签与 Issue 流程如何路由、以及输出与既有 ADR 冲突时必须如何显式标记。读完本文，你将掌握一套可复用的"先读域文档再动手"的仓库探索工作流，并理解该协议背后由 CONTEXT.md、docs/adr/ 与 codemap.md 共同支撑的领域模型是如何在源码中落地成形的。

一、协议概览：为什么 Agent 需要一份"领域文档消费协议"

oh-my-opencode-slim 是一个运行在 OpenCode 之上的多 Agent 编排插件，仓库内部同时存在多种角色：编排器（orchestrator）、多个专家子代理（explorer、librarian、oracle、designer、fixer、observer）、动态生成的 councillor 子代理，以及由 hook、skill、tool 组成的运行时子系统。当这些 Agent 以编程方式探索该仓库时，如果各自使用不同的术语、忽略架构决策记录、或自行发明概念名称，就会产生漂移：Issue 标题、重构提案、测试命名无法对齐，甚至与既有决策直接矛盾。

domain.md正是为解决这个问题而存在的消费侧协议（consumption-side protocol）：它不规定仓库的领域模型本身，而规定 Agent 在探索代码库时应如何消费仓库的领域文档——读什么、用什么词、缺文件怎么办、与 ADR 冲突怎么表态。它与仓库根部的 AGENTS.md（仓库操作规范）、CONTEXT.md（领域术语表）、codemap.md（架构地图）共同构成一套自洽的文档体系。

二、探索前的必读清单：CONTEXT.md、ADR 与 codemap

domain.md规定，Agent 在深入任何目录之前必须读取以下三份仓库根级文档：

1. CONTEXT.md —— 领域术语表与架构叙事

CONTEXT.md 是项目的领域词汇表（domain glossary），位于仓库根目录。协议明确要求：定义描述"术语是什么意思"，而非"如何实现"——这是与 codemap（讲实现结构）之间的根本分工。其核心内容包括：

术语表还专门开辟了Flagged一节，记录"真实存在但不阻塞"的术语碰撞与历史漂移：例如 "Presets" 一词同时指插件级 per-agent override 集合与 council 的 councillor 阵容（同一单词、不同 JSON 路径与类型）；配置键的命名风格在 snake_case（disabled_agents、main_pane_size）与 camelCase（autoUpdate、backgroundJobs）之间混用且无文档规则。这些标注的价值在于：让 Agent 在写作时意识到碰撞的存在，而不至于在 Issue 或提案中造成歧义。

2. docs/adr/ —— 架构决策记录

docs/adr/ 存放仓库的架构决策记录（Architecture Decision Records）。协议要求：在进入将要工作的区域之前，先阅读触及该区域的 ADR。仓库当前收录的 docs/adr/001-session-reflection-mode.md 是一个很好的样例——它完整记录了/reflect --sessions会话考古模式的决策过程：

• 实现方式决策：采用 prompt-only（仅扩展 reflect 技能的 SKILL.md），不新增代码工具或命令 hook，理由是与/reflect现有工作方式一致、LLM 已有 Read/Write/Bash 工具、符合 YAGNI；
• 命令语法决策：移除从未发布的--global，新增--sessions与--last N，如/reflect --sessions --last 20；
• 会话发现决策：LLM 读取~/.local/share/opencode/log/opencode.log并 grepsession.id=ses_[a-f0-9]+提取会话 ID，并给出了日志样例；
• 存储位置决策：反思摘要统一存放于~/.config/opencode/oh-my-opencode-slim/reflections/（sessions/、weekly/、monthly/ 分层），并附带了备选方案对比表（XDG 目录、项目本地目录、不落盘）及取舍结论；
• 两阶段架构决策：先逐会话反思、再聚合（session → weekly → monthly 层级聚合），聚合基于 20k~30k tokens 的精炼摘要而非原始会话；
• 缓存模式与 JSON 摘要 Schema：LLM 自管缓存（存在即加载），每条会话产出包含session、goal、success、frictions、recommendations、confidence等字段的结构化 JSON，并给出 0.9-1.0 / 0.7-0.9 / 0.5-0.7 / <0.5 四档置信度评分标准。

这份 ADR 展示了协议所期望的 ADR 形态：包含背景、决策、理由、备选方案、落盘结构、schema 与后果，使后续 Agent 可以低成本继承决策上下文。

3. codemap.md —— 架构地图

codemap.md 是仓库自身的架构地图，被 AGENTS.md 引用。协议要求：在进入某个目录做深度工作之前，先读它来了解模块职责与集成点。仓库根部 codemap 的内容包括：

• 系统入口点表：package.json（清单与发布脚本）、src/index.ts（插件引导组合根，聚合 agents/tools/MCPs/hooks/后台任务板/面试/缓存监控/orchestrator-wake/TUI preset 切换等，并导出 v1/v2 双入口）、src/cli/index.ts（安装与引导 CLI）、src/config/schema.ts（Zod 配置 schema 事实源）、scripts/generate-schema.ts（由 schema 生成 oh-my-opencode-slim.schema.json）；
• 目录地图：src 下 agents、cli、config、hooks、interview、mcp、multiplexer、skills、tools、utils、v2、companion 等各目录的职责摘要与各自的 src/codemap.md 子地图入口；
• 运行时控制流：插件启动（config 加载 → agent 定义 → 工具/MCP 注册 → hook 挂载）、交互请求处理（orchestrator prompt 路由 → 工具解析 → hook 转换）、委托执行（后台任务板 + task-session-manager + orchestrator-wake + TUI 客户端 pane 生命周期）、安装/发布路径；
• 关键跨模块集成点：如src/hooks/task-session-manager/依赖src/utils/background-job-board.ts等一组工具模块且只经由src/hooks/cache-safe-injection.ts注入提示词；src/multiplexer/仅客户端使用，由src/dependency-contract.test.ts的 I1 不变量强制约束；
• 推荐阅读顺序：codemap.md→src/codemap.md→ 相关子系统子地图。

三、静默容错规则：缺失文档时"安静地继续"

domain.md对文档缺失场景给出了明确的纪律：如果上述文件中的任何一个不存在，Agent 应当静默继续（proceed silently）——不标记缺失、不主动建议创建。原因在于：/domain-modeling技能（经由外部技能/grill-with-docs与/improve-codebase-architecture触发，并非本仓库内置技能）会在术语或决策真正得到解析时才按需（lazily）创建这些文件。

这条规则把"文档建设"与"文档消费"解耦：Agent 探索代码库是第一优先级，文档补齐是领域建模技能在被显式调用时的职责，二者不应互相阻塞。这也意味着协议本身是宽容的——它不把"文档齐全"当作探索的前置条件。

四、术语纪律：用术语表的词汇说话

协议对 Agent 输出的词汇选择有硬性要求：当输出需要命名一个领域概念时（无论出现在 Issue 标题、重构提案、假设还是测试名中），必须使用 CONTEXT.md 中定义的术语，不得漂移到术语表明确回避的同义词。术语表中就明确列出了被拒的同义词：explore应使用explorer，frontend-ui-ux-engineer应使用designer。

这背后是一条实用信号机制：如果所需概念在术语表中还不存在，那是一个值得注意的信号——要么是 Agent 正在发明项目不使用的新语言（应重新考虑措辞），要么是术语表存在真实缺口（值得为/domain-modeling记录）。换句话说，术语表的完备度被当作领域语言一致性的晴雨表。

五、Triage 与标签体系：从角色到仓库标签的翻译层

协议指明：运维层面的 triage 角色及其仓库标签，以 docs/agents/triage-labels.md 为事实源（source of truth），并配合 docs/maintainers.md 使用；外部 PR 的 triage 策略则位于 docs/agents/issue-tracker.md。

角色到标签的映射

triage-labels.md将mattpocock/skills中triage技能的规范角色名映射到本仓库 Issue 跟踪器的真实 GitHub 标签字符串。其定位是"角色是技能行为，字符串是仓库策略"的翻译层：

三个关键注释值得展开：其一，needs-triage刻意没有标签——未贴标签的 Issue 隐式处于 needs-triage 状态，这避免了"贴标签来标记未评估"的冗余；其二，ready-for-agent与ready-for-human都映射到good-to-code，区别在于由谁实现（Agent 还是人），而status:in-review是独立的人工审查状态（代码已存在待审查），不得贴给仍需实现的 Issue；其三，status:in-review、release、Share Your Thoughts、community-preset四个仓库标签刻意处于 triage 分类法之外，/triage不得应用它们。

路由与关闭流程

docs/maintainers.md 进一步给出了完整的运维流程：bug 报告与功能请求进 GitHub Issues，安装/排障/使用类问题去 Telegram 渠道；路由新 Issue 时，bug 或 feature 走/triage（技能由npx skills add https://github.com/mattpocock/skills --skill triage安装，标签映射已内置，无需运行/setup-matt-pocock-skills），支持请求则简要回复并引导去 Telegram。关闭策略上，仓库当前手动关闭 Issue、不使用 stale-bot 自动化。

Issue 与 PR 的操作约定

docs/agents/issue-tracker.md 给出了基于ghCLI 的完整操作约定，并强调写操作（创建/贴标/评论/关闭）必须指向上游跟踪器，显式传--repo alvinunreal/oh-my-opencode-slim（或设置GH_REPO），否则在 fork 克隆中裸gh命令会误改自己的 fork。其 PR 策略要点是：PR 被当作"附带代码的功能请求"进入 triage 队列，但只做类别标注（bug/enhancement），不进入 triage 状态机、永不自动关闭；护栏包括按authorAssociation过滤（保留 CONTRIBUTOR/FIRST_TIME_CONTRIBUTOR/FIRST_TIMER/MANNEQUIN/NONE，丢弃 OWNER/MEMBER/COLLABORATOR）而不是按 PR 内容过滤，且 PR 计数不得混入 Issue triage 统计。

六、ADR 冲突标记：宁可显式，不可静默覆盖

协议对 Agent 输出与既有 ADR 冲突的情形给出了明确的处理方式：显式表面化（surface it explicitly），而非静默覆盖。domain.md提供了标准句式模板：

Contradicts ADR-001 (session reflection mode) — but worth reopening because…

这条纪律的工程价值在于：ADR 是团队决策的持久化记录，静默推翻会让后续读者失去决策上下文。显式声明冲突（哪怕结论仍是"值得重开"）至少保证了决策轨迹可追溯、可被其他 Agent 或人类维护者复核。

七、源码层面的领域模型佐证：协议背后的实现形态

domain.md提到的领域词汇并非纸上谈兵，而是可以在源码中一一对位的。以术语表中两类最重要的 Agent 概念为例：

Councillor：从预设到动态子代理

council-agents.ts 中的buildCouncillorAgents（第 14~50 行）是"Councillor"一词的落地实现：它遍历council.default_preset（缺省'default'）对应 preset 的每个条目，把每个 councillor 构造成名为councillor-<name>的动态 AgentDefinition——前缀常量定义在第 5 行（COUNCILLOR_AGENT_PREFIX = 'councillor-'），加前缀的原因在注释中写明：裸名称（如alpha）可能与 OpenCode 保留的 agent 类型名冲突。若配置了多模型回退链（cfg.models.length > 1），则把_modelArray挂到 agent 上并清空单模型字段，避免单模型字段覆盖回退链。第 56~60 行的getCouncillorSeatName则是前缀的逆运算，用于把councillor-alpha还原为用户可见的座位名alpha。这正是 CONTEXT.md 中 "Councillor is registered ascouncillor-<name>from the council preset" 与 "Not hidden; visible in the TUI as panes" 的实现依据。

Council 合成器：无工具、结构化报告

council.ts 中的createCouncilAgent对应术语表里的 "Council"（multi-LLM agent，运行若干 councillor 并综合其观点）。其提示词明确声明 council agent 是"多模型共识合成器"、不自行派发 councillor（由 orchestrator 负责派发并提供结果）、且没有任何工具（合成仅基于上下文中的 councillor 响应）。输出强制包含Council Response、Per-Councillor Details（必须使用每个 councillor 的精确座位名，如alpha，而非模型标签）、Council Summary（Consensus Level 取unanimous|majority|split、Agreed Points、Disagreements + resolution、Remaining Uncertainty、Recommended Action）三部分——这与 docs/council.md 中描述的"council 响应包含合成答案、逐 councillor 详情、共识评级"完全一致，也与 CONTEXT.md 对Consensus的定义（unanimous/majority/split）逐字对位。权限方面，它使用createSynthesisOnlyPermission()（仅合成、无文件/命令能力），从源码结构看这是对"read-only advisor"定位的权限层落实。

这种"文档定义术语、源码落实行为、测试与 schema 保证一致性"的结构，正是domain.md协议想要 Agent 在探索时建立的心智模型：术语表讲语义、ADR 讲决策、codemap 讲结构，三者互相印证。

八、实战工作流：一次符合协议的领域探索

将domain.md的规则串起来，规范的探索流程是：

1. 读根级文档：先读 CONTEXT.md 建立术语表心智模型，扫一遍 docs/adr/ 找出与任务区域相关的 ADR，再读 codemap.md 定位模块职责与集成点（若缺失任一文件，静默继续）；
2. 定位目标区域：依据 codemap 的目录地图进入对应子系统的 codemap.md（如涉及 agents 就读 src/agents/codemap.md），并按推荐阅读顺序逐层深入；
3. 用术语说话：输出（Issue 标题、重构提案、测试名）一律使用术语表词汇，遇到新概念先判断是术语表缺口还是自造语言；
4. 对齐运维流程：涉及 Issue/PR 时，遵循 docs/agents/triage-labels.md 的标签映射、docs/maintainers.md 的路由流程与 docs/agents/issue-tracker.md 的gh操作约定（写操作务必指向上游仓库）；
5. 冲突显式化：若结论与既有 ADR 相悖，用标准句式显式声明冲突，交由人类或后续 Agent 复核决策轨迹。

结语

docs/agents/domain.md虽短，却是 oh-my-opencode-slim 多 Agent 协作体系的"探索宪法"：它以最小规则集约束了术语一致性（CONTEXT.md）、决策继承（ADR）、结构导航（codemap）、运维路由（triage-labels + maintainers + issue-tracker）与冲突处理（显式标记）五个方面，同时以"缺失即静默"的宽容条款保证了探索永不阻塞。对于希望为该仓库贡献代码、撰写 Issue 或构建技能的研究者而言，这套协议是进入代码库前最值得先读的一份文档——它让你从一开始就用这个项目自己的语言思考。

• 人工智能
• AI Agent
• Agent 编排
• AI 技能