项目仓库 PRD 接入指南
在自有代码仓库中接入 Heicode 智能体：提交 .heicode/prd.md、里程碑规划格式、扫描状态与项目状态说明。
Heicode 项目仓库 PRD 接入指南
适用于需要在自有代码仓库中使用 Heicode 智能体的团队。
PRD 模板下载：请依次进入「企业资源」并点击「GitHub 组织绑定」；在绑定的仓库清单上方，点击「查看或下载 PRD 模板」并按格式编写；最后确保将该文件放置在每个目标仓库的 .heicode/prd.md 路径下，平台即可自动读取其里程碑与进度。
一、整体流程
项目成员在仓库中提交 .heicode/prd.md（需求文档）
↓ 平台读取到该文件，作为整条流程的起点
平台据此生成技术设计（.heicode/sdd.md）与任务拆解（.heicode/task.md）
↓ 提交送审
企业评审人（AIE）人工审核
↓ 审核通过
团队即可在该仓库上让智能体开始工作未提交 .heicode/prd.md 时，后续步骤不会启动。平台不会推断未写明的需求。
二、目录结构
以下目录位于项目仓库根目录：
仓库根目录/
└── .heicode/
├── prd.md 需求文档，由项目成员编写
├── sdd.md 技术设计，平台生成，也可自行编写
├── task.md 任务拆解与阶段划分，平台生成，也可自行编写
└── config/ 受管配置，由企业管理员下发路径为唯一约定，无备选位置
平台不会尝试 PRD.md、docs/prd.md、README.md 等其他位置。未找到 .heicode/prd.md 时，将明确提示「缺少 .heicode/prd.md」。
采用单一路径是有意设计：若平台同时接受多个位置，一段时间后将无法确认哪一份是当前有效版本。
技术设计与任务拆解同理，分别只读取 .heicode/sdd.md 与 .heicode/task.md。
三、需求文档的前置要求
以下为强制要求，未满足时平台不会写入：
| 要求 | 未满足时的处理 |
|---|---|
路径为 .heicode/prd.md | 提示「缺少 .heicode/prd.md」，流程不启动 |
| 正文非空白 | 不写入空文档 |
| 内容为合法 UTF-8 文本 | 拒绝写入 |
| 不超过单版本字节上限 | 不截断、不写入，以避免保存不完整的需求内容 |
| 正文中不含明文凭据 | 检出疑似密钥、令牌或密码时拒绝写入 |
关于凭据
需求文档会进入版本库、被生成链路读取、并显示在审批界面上。因此文档中出现的任何凭据，等同于向所有可访问该项目的人员公开。
如需说明某项凭据，请描述其用途，不要写入具体取值：
- 推荐写法：调用支付网关需要一个 API 密钥，由运维在企业资源中绑定
- 不推荐：直接写出密钥字符串
送审与定稿期间的文档写锁
项目进入「待审核」或「已通过」状态后，仓库中对 .heicode/prd.md 的修改将不再被写入，状态显示为「文档写锁生效」。
如需修改需求，请先在控制台将项目退回草稿状态。此机制用于确保审核内容与实际执行内容一致。
四、需求文档编写说明
4.1 仅里程碑规划有格式要求
需求文档正文的章节划分、顺序与详略程度由编写者决定，平台不解析、不提示。
唯一有格式要求的是里程碑规划部分，因为平台需要据此生成项目进度、里程碑对比与成本归属。
锚点标题（以下任一均可识别）
# 里程碑
## 里程碑规划
### 3. 实施计划：
## Milestones标题层级相对于锚点
锚点使用 ## 时，里程碑使用 ###、小节使用 ####。
锚点使用 # 时，里程碑使用 ##、小节使用 ###。
因此规划部分可以嵌入文档的任意章节深度。
示例
## 里程碑规划
### 网关接入
- 目标日期: 2026-09-15
- 开始日期: 2026-09-01
先完成入口打通，本阶段不接入计费。
#### 鉴权改造
- 目标日期: 2026-09-08
#### 灰度放量
- 目标日期: 2026-09-15
### 计费打通
- 目标日期: 2026-09-30属性块规则
- 属性块为标题行之后紧接的连续列表项，以
-、*或+起始，其间允许空行 - 遇到第一个既非列表项也非空行的内容即结束
- 属性块之后至下一个标题之间的正文为自由描述，平台不解析、不提示。在里程碑下补充说明属于正常写法
可识别的属性键（大小写不敏感，中英文冒号均可）
| 含义 | 可用写法 |
|---|---|
| 目标日期 | 目标日期 / 目标完成日期 / 截止日期 / 交付日期 / 完成日期 / due / due date / deadline / target date |
| 开始日期 | 开始日期 / 计划开始日期 / 起始日期 / start / start date |
日期取值统一为 YYYY-MM-DD。格式不符的属性会被丢弃并给出提示，但该里程碑本身仍会被识别，避免单个日期笔误导致整条里程碑丢失。
需要注意的几点
- 同一层级下名称重复时，平台会自动追加
#2、#3并给出提示。建议直接修正重复名称 - 小节出现在任何里程碑之前时，提示
orphan_section - 层级深于小节的标题不参与解析，并会给出提示
- 使用围栏（``` 或 ~~~）的代码块内的标题行一律跳过，因此文档中粘贴示例 Markdown 不会产生多余里程碑
- 不包含里程碑规划的需求文档同样合法，平台仅给出一条提示，不视为错误，但该项目不会有里程碑进度
4.2 里程碑标识
如需控制台统计返工、无效消耗以及按里程碑的成本归属，需要在合并请求上标注里程碑标识。以下两种方式任选其一：
在标题中标注：
修复登录超时 [milestone:m:第一阶段/s:登录链路]或使用以 milestone/ 起始的分支名：
milestone/m:第一阶段/s:登录链路其中 m: 为里程碑名称、s: 为小节名称，需与 .heicode/prd.md 中填写的名称一致。平台的节点标识由名称派生：里程碑为 m:<名称>，小节为 <父级标识>/s:<名称>。
未标注时，相关指标会显示「数据不足」并说明原因。平台不会推断成员与里程碑的对应关系，也不会以 0 代替未知值。
五、提交后的处理
5.1 扫描结果
平台每次读取仓库后会给出明确状态，每种状态对应一项具体处理动作：
| 状态 | 含义 | 需要的处理 |
|---|---|---|
| 已写入 | 读取成功且为新内容，已作为新版本保存 | 无 |
| 无变化 | 与当前版本逐字节相同 | 无，不会重复追加版本 |
| 缺少文件 | 仓库中不存在 .heicode/prd.md | 补充提交该文件 |
| 读取失败 | 无权限、限流、网络异常或非预期状态码 | 确认平台是否具备该仓库的读取权限 |
| 内容为空 | 文件存在但正文为空白 | 补充正文内容 |
| 超过上限 | 单版本字节数超限 | 精简内容，平台不会截断保存 |
| 非文本 | 内容不是合法 UTF-8 | 检查文件编码 |
| 检出凭据 | 正文中存在疑似明文凭据 | 移除凭据取值，改为描述用途 |
| 写锁生效 | 项目处于送审中或已定稿 | 先在控制台将项目退回草稿 |
| 本次未扫描 | 本轮扫描时间预算用尽 | 无，下一轮会继续扫描 |
5.2 项目状态
| 状态 | 含义 |
|---|---|
| 草稿 | 已登记，未送审。此阶段可自由修改文档 |
| 待审核 | 已送审，等待评审人（AIE）人工审核。文档写锁生效 |
| 已通过 | 准入门放行的唯一状态 |
| 已驳回 | 可修改后重新送审 |
PRD 核心就写清三件事：解决谁的什么问题（背景目标）、具体怎么解决（功能流程与交互）、怎样算成功（验收标准与数据指标）。格式上保持需求描述清晰无歧义、优先级明确，并让研发和测试能直接据此执行。
最后更新于