目录与路径约定

核心边界

.Knowledge/：知识环——业务知识文档与机读路由（见体系与原理 §2 多层记忆）
.task/：任务环——变更追踪与跨会话续作（不在 .Knowledge/ 内）
配置根（.cursor/.claude/.codex/.dsh）：规则环 + 技能环入口

Memory Coding 四环总览见体系与原理 §1。

目录职责

路径	职责
`.Knowledge/stock-docs/`	L3 架构、终稿、沉淀长文档
`.Knowledge/req-docs/`	L3 需求澄清、技术方案长文档
`.Knowledge/topics/`	L2 主题摘要（硬约束、边界、路由指针）
`.Knowledge/template/`	终稿/技术方案模板
`.Knowledge/index.md`	人类可读索引
`.Knowledge/manifest-routing.json`	L0 机读路由骨架（task/topic/`topicDependencies`/`topicMetadata`）
`.Knowledge/matchers/*.json`	L1 关键词分片（`id` + `includeAny`/`includeAll` 资格词、`excludeAny`/`excludeAll` 否决词），由 `matcherPath` 直链；match 只读一片
`.Knowledge/migration-report.md`	历史版本 `f2s-kb-migrate` 落盘的迁移对照表与拟删除路径列表（该技能已移除，存量文件可保留）
`.task/`	变更追踪任务清单目录，本地运行态、默认进 `.gitignore`。多人协作时按 `<developerId>/` 再分一层，两种形态见下文 §`.task/` 的两种形态。仅当 `changeTracking.*` 为 `true` 或显式调用 `f2s-req-plan` 时创建
`配置根/rules/`	规则文件（Cursor `.mdc`，Claude `.md`）
`配置根/skills/`	技能定义（`SKILL.md`）
`配置根/template/`	（废弃）不再写入；历史目录可清理
`.codex/AGENTS.md`	Codex 统一入口与加载说明
`.dsh/AGENTS.md`	DeepSeek Harness 目录指针；完整项目入口仍是根 `AGENTS.md`
`.dsh/topics/`	DeepSeek Harness 按需读取的规则长文镜像
`flow2spec.config.json`	项目根配置，控制 `subAgent`、`switchAgentVerification`、`changeTracking`（嵌套对象，含 `feat` / `fix` / `implement` 三个子项）

多端提示与路径表见使用说明 § 一（详表单点维护）；权威仍为 Read(flow2spec.config.json)。

路径约束

.Knowledge/topics 是知识路由主题层，允许并鼓励通过 f2s-* 技能维护。
f2s-kb-build 从 .Knowledge/stock-docs 读，更新 .Knowledge/topics、.Knowledge/index.md、.Knowledge/manifest-routing.json、.Knowledge/matchers/*.json。
实现类任务统一读取 .Knowledge/req-docs/*.md。
manifest-routing.json 与 matchers/*.json 由 f2s-* 技能流程维护；不再使用 .Knowledge/manifest-matchers.json（flow2spec init 会删除遗留文件）。
.task/ 与 .Knowledge/update-check.json 是本地运行态，默认不进 Git；flow2spec init 会非破坏式补充 .gitignore。任务进度是个人过程草稿，知识库才是团队沉淀，两者分线管，具体形态见下文 §.task/ 的两种形态。

`.task/` 的两种形态

.task/ 有两套摆法，取决于 flow2spec.config.json 里 collaboration 的解析结果：

模式	触发条件	路径
legacy 单根	`collaboration.enabled: false`，或跑到最后一档仍解析不出 developerId	`.task/todo.json` · `.task/active/` · `.task/completed/`
按 developerId 隔离	`collaboration.enabled: true`（默认）且能解析出 id	`.task/<developerId>/todo.json` · `.task/<developerId>/active/` · `.task/<developerId>/completed/`

两种形态下 active/ 与 completed/ 的子目录命名规则一致：进行中直接用 task-name；已归档改成 <YYYYMMDD>-<task-name>（日期在前）。

developerId 的解析顺序

自顶向下取第一个能落地的：

flow2spec.config.json → collaboration.developerId（非空但含非 ASCII 或全被 [^a-z0-9] 过滤成空的会直接报错，让用户显式修正配置，不再静默降级 legacy）
git config user.email 的 @ 前缀
git config user.name
上面都拿不到 → legacy 单根

第 2、3 档如果拿到的是中文/日文/其他非 ASCII 字符串，会退化到 dev-<sha256 前 8 位> 的 hash id 作为兜底，跨机器稳定；解析器同时把这次降级放进返回值的 warnings，供调用方决定是否提示用户改成显式的英文标识。

为什么在本地也要按人分层

.task/ 已经不进 Git 了，本地机器天然按人隔离，但 <developerId>/ 这一层仍然有意义，覆盖三个边界：

同一台开发/构建机上多个账号共用（devcontainer、共享 Mac mini、跳板机）
AI 需要一个稳定的 TASK_ROOT 边界，防止跨读别人未归档的任务上下文（配置根 rules/f2s-task 是硬约束）
若团队日后约定把 completed/ 白名单加回 Git 做团队归档，<developerId>/ 结构直接生效，不用回头改代码

从 legacy 迁到隔离模式

开启 collaboration.enabled 之前 .task/active/ 里可能还有进行中的任务，f2s-* 技能不会自动搬：如果多人共用过同一个 legacy .task/，自动挪目录会把别人未完成的任务卷进当前 developer 的目录。用户确认后手动 mv .task/active .task/<id>/active（completed/ 同理）即可完成迁移。

主题元数据

manifest-routing.json.topicMetadata 是 topic 的机读治理元数据，只用于盘点、过滤、路由审计、升级补缺和阅读预期；不参与 matcher 命中，不决定是否读取 topic，不作为执行强制性的事实源，也不驱动 topicId 或文件名变化。执行强制性始终以 AGENTS.md、rules、skills 与 topic 正文中的明确要求为准。

topicMetadata 独立于 topicPaths，key 必须是 topicPaths 中已存在的 topicId。新增 topic 时有明确证据可同步写入；仅补分类不得创建 topic、重命名 topic 或拆分 topic。

字段	取值	说明
`primary`	`feature` / `module` / `config` / `policy`	单值主分类。取 topic 最核心的性质，读 topic 正文后写入。
`tags`	`feature` / `module` / `config` / `policy` 数组	可选次要分类，不得与 `primary` 重复。
`confidence`	`manual` / `inferred`	`manual` 为人工确认；`inferred` 为有明确证据推断；证据不足时不写 metadata，并在摘要列为待确认。

类型含义：

类型	阅读预期
`feature`	已落地业务/产品能力背景
`module`	目录、包、模块边界与工程结构
`config`	配置项、开关、默认值、初始化参数
`policy`	流程、规则、约束、门禁、禁止项、agent 编排、技能步骤

主题粒度

topic 是路由摘要与关键边界，细节放在 stock-docs/。若对应 stock-doc 超过 300–500 行、matcher includeAny 超过 12 个，或正文出现 3 个以上不相干职责域，建议拆成主 topic + 可独立命中的子 topic。