---
name: nebflow-docs
description: Nebflow 技术文档域知识——写作规范（准确/简洁/结构化/示例驱动/不过度展开）、中英双语文档同步、导航结构维护、文档一致性联动（代码改了文档跟着改）、产出路径纪律。Use when 编写或更新 Nebflow 的 README、API 文档、架构指南、CHANGELOG 等文档。
when_to_use: Nebflow 项目文档任务（README、API docs、架构指南、CHANGELOG、代码注释），中英文皆可；文档内容必须与代码实现一致。
language: zh
status: active
last_verified: 2026-09-14
---

# Nebflow Docs — 技术文档域知识

## 写作规范

- **准确**：文档内容与代码实现一致，不臆测；写前先读相关代码/规格。
- **简洁**：一句话能说清的不用两句；删除冗余修饰。
- **结构化**：标题、列表、代码块组织内容。
- **示例驱动**：用具体代码示例说明概念——一个好示例胜过三段解释。
- **不过度展开**：技术细节放对应章节，Intro 只概括背景和目的。

## 双语与导航

- 中英双语文档保持内容同步——一侧改了另一侧跟上。
- 维护文档导航结构（如 DOCS_NAV）：新增文档要挂进导航，删除文档要摘出条目——信息可发现性是文档工程的一部分。

## 文档一致性联动

改动涉及架构、工具系统、提示词机制、实体定义等基础设施时，同步更新所有相关内容：

1. 提示词（`~/.nebflow/prompts/`）受影响部分；
2. Agent 记忆中的过时条目；
3. README.md、CODEBASE.md（如存在）、代码注释；
4. 工具 description 与外部工具 JSON 配置。

**原则：代码改了，文档/提示词/记忆也要跟着改。不留过时内容。**

## 产出路径纪律

- 文档产出落 `~/.nebflow/docs/<域>/`（Nebflow 项目域为 `docs/Nebflow/`），禁止 /tmp。

## 交付口径

- 列出改动文件清单；说明文档变更的 WHY（代码改了/新增了功能/过时了）；标注哪些重写、哪些更新。

## 图文报告·图片内嵌（执行面副本）

给**作者**的图文报告（人读件）形态硬要求——**权威面 = 项目仓 `AGENTS.md`「作者图文报告·图片内嵌」节**；改本条须与同节同步改，禁两套口径。

- **图片一律以图语法内嵌**：`![](<绝对路径>)`；🔴 禁止只给路径文本清单冒充报告正文——路径/文件清单只能作附录或清单件（证据批次的 `MANIFEST.md` / `index.json`）。
- **大图集（> 20 张）**：正文只内嵌**决策相关子集** = 对照拼图（`cmp-*` 三态并排）+ 逐项裁定配对图（`adj-R<n>-opt{A,B}`）；全量清单进附录/清单件，禁逐张平铺正文。
- **内嵌路径须落在可服务面**：`<ws>/.nebflow/evidence*/**` 或 `~/.nebflow/{projects,uploads,plots,workspace-items,voice-models}/**`；`~/.nebflow/docs/**` 会被拒（reason `credential-path`）。工作区路径含空格为常态时，作者侧渲染另依赖 nf-file 编码面（在册缺陷 #487），未验证生效须标注「作者侧渲染待验」。