智能体执行需求总入口 · Agent Handoff Spec v1.0
本文是 Xisound 算法部文档站 P1-P3 阶段执行的唯一入口。 任何"文档管理员智能体 / 文档迁移智能体 / 内容编写智能体"在执行任务前,必须完整读完本文, 然后再按 §10 PR 自查清单逐项核对自己的产出。
本文不重复 6 份正式规范的细节,只做"骨架式提炼 + 关键链接 + 红线清单"。 当本文与 6 份正式规范冲突时,以 6 份正式规范为准(本文若发现冲突请反馈修订)。
1. 必读 6 份规范(每份 1 句话用途)
执行任何 P1-P3 阶段任务前,必须按以下顺序通读:
| # | 规范文件 | 1 句话用途 | 强制等级 |
|---|---|---|---|
| 1 | md-writing-spec.md |
MD 写作主契约 · frontmatter / 标题层级 / 表格 / 代码 / 链接的全部硬性规则 | ⭐⭐⭐ |
| 2 | brand-color-system.md |
色板权威 · 三色法典 + 产品 6 色 L0-L5 + Admonition 6 组语义配色 + 错误状态色破例 | ⭐⭐⭐ |
| 3 | format-spec-changelog.md |
9 条视觉决议底座 · .xy-quote / .xy-glossary / .xy-gantt / .xy-stack / .xy-frac / .xy-mermaid-modal / .xy-math 等组件的 CSS/JS 完整代码与使用示例 |
⭐⭐⭐ |
| 4 | nav-display-spec.md |
站点级配置 · Stripe 三栏布局规范 + KaTeX 动态加载 + status 徽章 + 一级目录占位模板 | ⭐⭐ |
| 5 | folder-structure-spec.md |
IA v3 物理目录结构 · 9 个一级目录 + 13 稳态产品结构 + 命名规范方案 4 | ⭐⭐⭐ |
| 6 | migration-plan-2026Q2.md |
4 阶段 12 周迁移计划 · P0/P1/P2/P3 各自的任务清单与验收标准 | ⭐⭐ |
⭐⭐⭐ 表示"必读且违反即拒",⭐⭐ 表示"必读但条目可酌情"。
2. P0 已完成清单 + P1.1a 示范完成(智能体不要重复做)
P0 基础设施阶段 + P1.1a 示范迁移已经由 Cline 在 2026-05-11 全部落地,以下 10 项已就绪,智能体不要再动:
- ✅
docs/assets/stylesheets/xiyin-brand.css— 三色法典 + 产品 6 色 L0-L5 + Stripe 三栏 11 变量(light/dark 双套) - ✅
docs/assets/stylesheets/xiyin-extra.css— 9 决议组件 CSS(.xy-quote / .xy-glossary / .xy-term / .xy-gantt / .xy-stack / .xy-frac / .xy-mermaid-modal / .xy-mermaid-zoom-btn 等,共 ~2141 行) - ✅
docs/assets/stylesheets/xiyin-patch.css— Admonition 6 组语义配色(信息组紫霞 / 提示组极光青 / 警告组玫瑰金 / 危险组赤陶 / 示例组古铜金 / 引用组中性灰) - ✅
docs/assets/javascripts/(7 个 JS:xiyin-stars / xiyin-comets / xiyin-mermaid / xiyin-mermaid-zoom / xiyin-katex / xiyin-wrap / xiyin-toc-merge) - ✅
overrides/main.html— Hero 自动渲染 + body class 注入(level-l1a/b/l2/l3 + xy-stripe-layout)+ KaTeX 按 frontmatter 动态加载 + status 徽章 + deprecated 横幅 - ✅
mkdocs.yml— IA v3 nav 9 个一级条目(首页 / 01战略 / 02产品 / 03平台 / 04部门 / 05标准 / 06客户 / 07工程 / 99归档)+ KaTeX CDN + redirects 插件 + 16 项 features - ✅
docs/00-home/ ~ 99-archive/— 9 个 IA v3 一级目录物理结构 + 占位 index.md 全部就位 - ✅ 6 份正式规范文档 + 1 份索引页 + 本文(智能体入口)
- ✅ P1 启动文档:
p1-migration-task-list.md(P1 阶段可执行级任务表 · 含 frontmatter 升级表 + redirect_maps 草案 + P1.1b-P1.4 接力清单) - ✅ P1.1a 示范迁移完成:
D0-company/00-vision/→01-strategy/00-vision/(6 文件 · 自动化脚本scripts/p1-migrate-vision.ps1支持 dry-run/Apply/Rollback · build 0 ERROR)
2.1 P1.1a 已知问题(留给 P1 智能体处理)
迁移后 mkdocs build WARNING 数从 104 增加到 120(+16),全部是相对路径内部链接失效:迁移到新位置的文件中含 ../05-standards/todo-list.md 等链接,基于旧位置 D0-company/00-vision/ 解析正确,但在新位置 01-strategy/00-vision/ 下解析为不存在的路径(如 01-strategy/05-standards/todo-list.md)。
这是 P1 内容迁移阶段预期问题(migration-plan §4.4 已登记)。智能体在执行 P1.1b ~ P1.4 时,必须在迁移每个文件时同步更新其内部相对链接 — 推荐用 sed/PowerShell 脚本批量处理。
修复模板(以 01-strategy/00-vision/strategy-3y.md 中的 ../03-finance/financial-model.md 为例):
- 旧链接:../03-finance/financial-model.md (基于旧位置 D0-company/00-vision/,指向 D0-company/03-finance/financial-model.md)
- 新链接:../03-finance/financial-model.md (基于新位置 01-strategy/00-vision/,需要 P1.1b 把 D0-company/03-finance/ 也迁到 01-strategy/03-finance/ 后,链接就自动正确了)
所以这 16 个 warning 会在 P1.1b 完成后自动消解(因为 01-strategy/03-finance/、01-strategy/05-standards/(P1.1c 后路径变 05-standards/,需要再调整一次链接)等目录会陆续就位)。
智能体 P1 阶段验收:把 warning 数控制在 ≤ 104(基线)+ ≤ 16(过渡期 P1.1a 已知)= 120 即可。P1 全部完成时 warning 应回到 ≤ 104。
智能体进入 P1 阶段时,按 p1-migration-task-list.md §7 的 P1.1b ~ P1.4 接力清单执行即可,无需再动任何 CSS/JS/模板/配置。
3. MD 写作规范关键 7 条(违反即 PR 拒绝)
来源:
md-writing-spec.md(完整版有 19 章,本文只列最高优先级)
3.1 frontmatter 必填 9 字段
每份新建 / 迁移的 .md 文件 必须 在文件头有以下 frontmatter:
---
doc_id: D2-P1-xistudio-tech-arch # 唯一标识 · 数字段 + 类型前缀
title: XiStudio 技术架构设计 # 中文标题 · 不含 emoji 不含编号
status: draft # draft / review / published / deprecated
audience: internal # internal / external / agent
owner: AlgoDepartment / 你的名字
last_review: 2026-05-11 # YYYY-MM-DD
version: 1.0.0 # 语义化版本
tags:
- product
- xistudio
- architecture
legacy_doc_id: D2-products-P1-tech # 迁移文档必保留旧 doc_id
level: l3 # l1a/l1b/l2/l3 决定 Stripe 布局与字号
katex: false # 含数学公式时设 true
hero_show: false # 一级页面入口设 true
---
3.2 标题不跳级
H1 → H2 → H3 → H4 必须连续,不允许 H1 → H3 跳级。
H1 一篇文档只能有 1 个(由 frontmatter title 自动渲染),正文用 H2 起步。
3.3 表格不嵌 HTML
Markdown 表格里不允许嵌入 <div> / <span> / <br> 等 HTML。
若需要复杂排版,改用 pymdownx.tabbed Tabs 或 .xy-glossary 卡片网格(见 §6)。
3.4 Mermaid 用 xyL0-L5 / xySgL0-L5 主题类
flowchart LR
A[Device 输入]:::xyL1 --> B[Source]:::xyL3 --> C[Sink]:::xyL0不允许手写 style A fill:#5DDECF 等内联样式 — 一律用预定义的 xyL0/xyL1/xyL2/xyL3/xyL4/xyL5(节点)+ xySgL0~xySgL5(子图)。
3.5 Admonition 严格按 6 组语义选用
| 组 | 类型 | 用途 |
|---|---|---|
| 信息组 · 紫霞 | note / info / abstract |
一般说明、背景介绍、摘要 |
| 提示组 · 极光青 | tip / success / question |
最佳实践、成功案例、常见疑问 |
| 警告组 · 玫瑰金 | warning |
注意事项、潜在风险 |
| 危险组 · 赤陶 | failure / danger / bug |
错误、致命陷阱、已知 bug |
| 示例组 · 古铜金 | example |
代码示例、配置范例 |
| 引用组 · 中性灰 | quote |
引用他人观点、参考文献 |
不要为了"特殊视觉"而错用语义(如把"成功案例"放进 danger)。
3.6 9 视觉组件用 raw HTML + md_in_html
.xy-quote / .xy-glossary / .xy-gantt / .xy-stack / .xy-math 等 9 决议组件不能用纯 Markdown 表达,必须用 raw HTML 嵌入。MkDocs 已启用 md_in_html 扩展,可以放心使用:
<div class="xy-quote" markdown>
<div class="xy-quote-content">让上游算法看不见数据来自哪里 —— Source 模块的存在意义。</div>
<div class="xy-quote-author">XiStudio Architecture Council · 2026</div>
</div>
完整 HTML 模板见 format-spec-changelog.md §决议 1-9 各章节末尾。
3.7 不手写 hex 色值
任何颜色都通过 CSS 变量引用(var(--xi) / var(--L3-bg) 等),不允许在 .md 或 raw HTML 的 style="" 中直接写 #9D4EDD / #D4A574。
唯一例外:赤陶色 #B87A6F(错误状态色),它是三色法典之外的破例,只允许出现在 .callout.danger 体系内。
4. 命名规范关键 5 条
来源:
folder-structure-spec.md· 命名规范方案 4(数字段稳态 + 类型前缀过程 + doc_id 可选)
| # | 规则 | 示例 |
|---|---|---|
| 1 | 数字段稳态:目录用两位数字前缀,稳定不变 | 00-home / 01-strategy / 99-archive |
| 2 | 类型前缀过程:文件名用 <type>-<topic>.md 表达过程性内容 |
prd-v1.md / arch-overview.md / runbook-deploy.md |
| 3 | kebab-case 全小写:目录与文件名都用小写 + 短横线 | tech-arch.md(不要 TechArch.md / tech_arch.md) |
| 4 | doc_id 格式:<level>-<section>-<topic> |
D2-P1-xistudio-tech-arch |
| 5 | legacy_doc_id 必保留:迁移文档必须在 frontmatter 中保留旧 doc_id 用于 redirects 映射 | legacy_doc_id: D2-products-P1-tech |
5. 目录规范关键 6 条
来源:
folder-structure-spec.md· IA v3
5.1 9 个 IA v3 一级目录(顺序固定 · 不要新增)
| 目录 | 中文名 | 用途 |
|---|---|---|
docs/00-home/ |
首页 | 站点入口 + 总览 |
docs/01-strategy/ |
战略 | 公司愿景 / 战略白皮书 / 3 年 Roadmap |
docs/02-products/ |
产品 | P1-P10 产品矩阵(13 稳态产品结构) |
docs/03-platform/ |
平台 | 系统架构 / Backend / Frontend / DSPAlgo / Protocol |
docs/04-departments/ |
部门 | 各中心(产品/研发/商务/交付/运营)的中心级文档 |
docs/05-standards/ |
标准 | MD 规范 / 色彩规范 / 命名规范 / 本文 |
docs/06-customer/ |
客户 | 对外发布的客户专区(产品资料 / 技术支持 / 软件下载 / Demo) |
docs/07-engineering/ |
工程 | 测试 / 运维 / DevOps / 监控 |
docs/99-archive/ |
归档 | 旧文档归档区(只读 · 不删原则) |
5.2 13 稳态产品结构(02-products/ 下)
02-products/
├── index.md # 产品矩阵总览
├── P1-xistudio/ (L4 · 工坊 IDE)
├── P2-xidsp/ (L0 · 芯片)
├── P3-xiamp/ (L1 · 功放硬件)
├── P4-xibox/ (L1 · 音频盒)
├── P5-xialgo/ (L3 · 算法引擎)
├── P6-xitune/ (L2 · 调音工具)
├── P7-xitest/ (L2 · 测试工具)
├── P8-ximind/ (L5 · 云端智能)
├── P9-xiforge/ (L4 · 锻造工具链)
└── P10-xivst/ (L4 · VST 插件)
每个 P{N}-{name}/ 下推荐稳态结构:index.md / overview.md / prd-v1.md / spec.md / tech-arch.md / api.md / user-manual.md。
5.3 _dev/ 目录不进 nav
任何目录下名为 _dev/ 的子目录都是草稿/内部工作区,不会被 nav 收录,但 mkdocs build 会扫描它们。
草稿 PR 期间放 _dev/,定稿后再移到正式位置。
5.4 99-archive/ 不删原则
旧文档永远不删,只移到 docs/99-archive/<原路径>。
迁移时在新位置 frontmatter 标注 legacy_doc_id,在旧位置改 status: deprecated。
5.5 每个目录必须有 index.md
任何目录(包括 _dev/ 之外的所有子目录)都必须有一份 index.md,作为该目录的入口页。
index.md 模板见 nav-display-spec.md §5.3。
5.6 同级数字前缀允许跳号
01-strategy / 02-products / .../99-archive 不要求连续 — 允许跳号(如 02 → 05),只要保持升序即可。
跳号可用于"为未来留位"(如 08 / 09 可暂留空)。
6. 色彩规范关键 4 条
来源:
brand-color-system.md
6.1 三色法典锁定(永不修改)
| 名 | 角色 | hex | CSS 变量 |
|---|---|---|---|
| 曦紫 Xi | 主色 · 神秘哲思 | #9D4EDD |
var(--xi) |
| 玫瑰金 Yin | 副色 · 温暖工艺 | #D4A574 |
var(--yin) |
| 极光青 Sheng | 副色 · 科技灵动 | #5DDECF |
var(--sheng) |
6.2 产品 6 色 L0-L5(节点 + 子图均按层级配色)
| 层 | 名 | hex | 适用 |
|---|---|---|---|
| L0 | 深极光青 | #2E8D7E |
芯片 / SoC |
| L1 | 极光青 | #5DDECF |
硬件 |
| L2 | 香槟金 | #E8C9A0 |
测试调音 |
| L3 | 玫瑰金 | #D4A574 |
算法 |
| L4 | 浅紫 | #C77DFF |
工具 |
| L5 | 曦紫 | #9D4EDD |
云端 |
每色都有 --L{N} / --L{N}-bg / --L{N}-text 三件套 CSS 变量。
6.3 Admonition 6 组语义(违反即拒)
参见 §3.5 — 12 类 admonition 严格按 6 组语义选用,不允许"为视觉而错用语义"。
6.4 错误状态色 #B87A6F 唯一破例
赤陶色是三色法典之外的破例,仅限用于 .callout.danger / .callout.failure / .callout.bug 体系。
任何其他场景禁止使用赤陶色。
7. P1-P3 阶段任务索引
完整任务清单见
migration-plan-2026Q2.md,以下是高频锚点。
7.1 P1 · 内容迁移(2026 Q2 W1-W4)
migration-plan-2026Q2.md#p1-内容迁移· §4 P1 任务表- 主要工作:把
docs/D0-company / D1-divisions / D2-products / D3-architecture等旧 D 系列目录的 .md 文件,按 §5.1 IA v3 + §3.1 frontmatter 规范,迁移到新的 9 个一级目录中 - 验收:所有迁移文档 frontmatter 完整 + legacy_doc_id 已设 + 旧文件 status 改 deprecated + redirects 已配
- 关键产出:消除 mkdocs build 当前的 104 条
link target not foundwarning
7.2 P2 · 内容增强(2026 Q2 W5-W8)
migration-plan-2026Q2.md#p2-内容增强· §5 P2 任务表- 主要工作:把"纯文字段落"逐步替换为 9 决议视觉组件(.xy-quote / .xy-glossary / .xy-stack / .xy-gantt 等)
- 验收:每个 product 一级页 + 每份 PRD/spec/arch 文档都至少含 3 处视觉组件
- 关键产出:让站点视觉与
nav-demo/format-demo-0-current.html真实对齐
7.3 P3 · 客户专区(2026 Q2 W9-W12)
migration-plan-2026Q2.md#p3-客户专区· §6 P3 任务表- 主要工作:
docs/06-customer/对外发布版打磨 + 多语言基础设施 - 验收:外部审稿 1 轮通过 + i18n 插件接入完成
8. 执行流程图(智能体接到任务后)
flowchart TD
A[接到任务] --> B[读完本文 + 6 份规范]
B --> C{任务属于哪阶段?}
C -->|P1 迁移| D[逐文件迁移 · §3+§4+§5]
C -->|P2 增强| E[逐文件加视觉组件 · §3.6+§6]
C -->|P3 客户| F[多语言+对外打磨]
D --> G[mkdocs build 验证 0 ERROR]
E --> G
F --> G
G --> H{warning 是否未增加?}
H -->|是| I[填 §10 PR 自查清单]
H -->|否| J[修复 warning 来源]
J --> G
I --> K[提 PR · 等审核]
K --> L{审核通过?}
L -->|是| M[合并到分支]
L -->|否| N[按反馈改 · 回到 G]9. 红线清单(违反 = PR 立即拒绝)
| # | 红线 | 来源章节 |
|---|---|---|
| R1 | 修改 xiyin-brand.css 三色法典核心 hex(--xi/--yin/--sheng 既有值) |
§6.1 |
| R2 | 修改 overrides/main.html 现有的 Hero 自动渲染逻辑 |
§2 |
| R3 | 删除 nav-demo/ 下任何文件(P3 才整体归档) |
§2 |
| R4 | 在 .md 中手写 hex 色值(除 #B87A6F 在 danger 体系内) |
§3.7 / §6.4 |
| R5 | 在 .md 表格中嵌 <div>/<span>/<br> HTML |
§3.3 |
| R6 | frontmatter 缺少 9 字段中任意必填字段 | §3.1 |
| R7 | 标题跳级(H1→H3 等) | §3.2 |
| R8 | Mermaid 内联 style fill:#xxx |
§3.4 |
| R9 | Admonition 错用语义(如"成功"放进 danger) |
§3.5 |
| R10 | 删除 docs/99-archive/ 下任何文件 |
§5.4 |
| R11 | 提交 PR 前未跑 mkdocs build --clean 验证 |
§8 |
| R12 | mkdocs build 出现新增 warning(基线为 P0 完成时的 104 条) | §7.1 验收 |
10. PR 自查清单(每次提交前必填)
来源:
md-writing-spec.md§19.1 + §19.2
复制以下清单到 PR description,逐项打钩:
### MD 规范自查
- [ ] frontmatter 9 字段全部到位(doc_id / title / status / audience / owner / last_review / version / tags / level)
- [ ] 迁移文档已设 legacy_doc_id
- [ ] 标题层级未跳级(H1→H2→H3→H4)
- [ ] 表格未嵌 HTML
- [ ] Mermaid 用 xyL0-L5 / xySgL0-L5,无内联 style
- [ ] Admonition 按 6 组语义选用,无错位
- [ ] 9 视觉组件用 raw HTML(<div class="xy-quote" markdown>...)
- [ ] 无手写 hex(除 danger 体系的 #B87A6F)
### 命名规范自查
- [ ] 文件名 kebab-case 全小写
- [ ] 数字段前缀符合 IA v3
- [ ] 类型前缀符合(prd-/arch-/spec-/runbook-/api-)
- [ ] doc_id 格式正确
- [ ] 旧文件 legacy_doc_id 一一对应
### 目录规范自查
- [ ] 文件位于 9 个一级目录之内
- [ ] 目录有 index.md
- [ ] 草稿放 _dev/(若适用)
- [ ] 旧文件移到 99-archive/ 而不是删除
- [ ] redirects 已在 mkdocs.yml plugins.redirects.redirect_maps 中配置(若有迁移)
### 色彩规范自查
- [ ] 颜色全部用 CSS 变量,无手写 hex
- [ ] 产品节点用 L0-L5 对应层级
- [ ] Admonition 12 类按 6 组语义选用
- [ ] 错误场景才用 #B87A6F
### 构建验证
- [ ] 跑过 `python -m mkdocs build --clean` 0 ERROR
- [ ] warning 数未超过基线(基线 = 提 PR 时 main 分支当前数)
- [ ] 本地 `python -m mkdocs serve` 实际打开过新文档页 + 视觉无明显异常
- [ ] Mermaid / 数学公式 / 9 决议组件(若有)实际渲染验证过
### 红线检查(§9)
- [ ] 没有触犯 R1-R12 任一红线
11. 附录 · 快速链接表
| 资源 | 路径 |
|---|---|
| 视觉真相(套 0 · 9 决议) | nav-demo/format-demo-0-current.html(在分支根的 AlgoDepartment/06_docs/site-build/nav-demo/) |
| 视觉真相(Stripe 三栏) | nav-demo/demo-1-stripe-style.html(同上) |
| 9 决议 CSS/JS 完整代码 | format-spec-changelog.md §决议 1-10 |
| Stripe 三栏 Material 接管 CSS | nav-display-spec.md §3 |
| KaTeX 动态加载 Jinja2 片段 | nav-display-spec.md §4.2 |
| 一级目录 index.md 模板 | nav-display-spec.md §5.3 |
| status 徽章 + deprecated 横幅 | nav-display-spec.md §6.2 + §6.3 |
| 完整 CSS 变量清单 | brand-color-system.md §6 |
| Admonition 6 组对照表 | brand-color-system.md §4.2 |
| P0 任务与验收 | migration-plan-2026Q2.md §3.2 + §3.3 |
| P1 任务表 | migration-plan-2026Q2.md §4 |
| P2 任务表 | migration-plan-2026Q2.md §5 |
| P3 任务表 | migration-plan-2026Q2.md §6 |
12. 修订记录
| 版本 | 日期 | 修订人 | 改动 |
|---|---|---|---|
| 1.0.0 | 2026-05-11 | Cline / AlgoDepartment Doc Council | 首版 · P0 完成时同步发布,作为 P1-P3 智能体执行总入口 |
下一步:智能体接到 P1 任务时,先回到 §1 重新通读 6 份规范,然后回 §7.1 P1 锚点开始具体执行。 任何疑问 → 不要猜测,先看 6 份规范的细节;6 份规范没说的 → 在 PR 中显式提问,不要默认。