80 lines
5.8 KiB
Markdown
80 lines
5.8 KiB
Markdown
# LTJT 项目文件治理规则
|
||
|
||
本文件约束所有后续维护会话。用户指令优先；在没有新的明确指令时，必须遵守以下位置、同步和归档规则。
|
||
|
||
## 开始工作前
|
||
|
||
1. 依次读取根目录 `README.md`、`task_plan.md`、`findings.md`、`progress.md`。
|
||
2. 运行 `git status --short`，保留所有既有未提交改动；禁止 `git reset --hard`、`git clean` 或批量回退。
|
||
3. 通过 `agent设计规范/business-adaptation-registry.md` 定位业务，再读取对应业务页、Skill、Schema、mapping 和实现代码。
|
||
4. `archive/` 只供追溯，不能反向覆盖当前业务规则；若历史文件与活动源码冲突，以活动源码及当前契约为准。
|
||
|
||
## 根目录边界
|
||
|
||
允许的长期文件只有：
|
||
|
||
- 项目入口与约束：`README.md`、`AGENTS.md`；
|
||
- Planning with Files：`task_plan.md`、`findings.md`、`progress.md`；
|
||
- 构建与部署配置：`package.json`、锁文件、TypeScript、Docker、Compose、Git/Docker ignore 和环境示例；
|
||
- 本地秘密配置 `.env` 可以存在，但必须被 Git 忽略，不得读取、复制、归档或输出其内容。
|
||
|
||
禁止在根目录新增临时说明、交接副本、测试输出、ZIP、DOCX、截图、日志、浏览器状态或一次性脚本。新增内容必须进入下表规定的位置。
|
||
|
||
## 唯一目录职责
|
||
|
||
| 位置 | 唯一职责 | 禁止内容 |
|
||
|---|---|---|
|
||
| `agent设计规范/` | Agent Prompt、五个 Skill、业务模板、业务入口与稳定测试夹具的可编辑源 | 发布包、运行日志、历史版本副本 |
|
||
| `schemas/` | 当前解析态、执行态和 ERP 表单 Schema | 历史 Schema、运行结果 |
|
||
| `mappings/` | 当前 ERP 字段与生命周期 mapping | 探针输出、旧版本副本 |
|
||
| `chrome-extension/` | 当前 Chrome ERP 适配器源码 | 打包 ZIP、浏览器 profile |
|
||
| `control-plane/` | 当前 TypeScript 控制面源码、迁移和测试 | 编译后的 JavaScript |
|
||
| `LianSyn-platform/` | 当前平台页面与 Agent 解析适配器源码 | 本地任务输出、发布包 |
|
||
| `tools/` | 可复用构建器、测试、只读诊断与受控写入工具 | 工具运行结果、临时 JSON |
|
||
| `infra/` | 当前部署、备份、恢复和网关配置 | 本地秘密、数据库备份文件 |
|
||
| `samples/` | 脱敏且稳定的测试输入样例 | 真实客户资料、运行输出 |
|
||
| `.build/` | TypeScript 可重建编译输出；Git 忽略 | 人工维护文件、发布物 |
|
||
| `dist/` | 当前版本化交付物及机器可读发布清单 | 编译输出、无版本别名、松散 Prompt/示例副本、旧版本 |
|
||
| `reports/` | 当前会话临时验证输出；除 README 外应为空 | 长期证据、业务规则 |
|
||
| `quarantine/` | 无法安全解析的外部输入隔离边界 | 当前源码或已信任 fixture |
|
||
| `archive/` | 日期化、只读、可恢复的历史实现、证据、规划和发布物 | 当前入口或需要运行时读取的文件 |
|
||
|
||
## Planning with Files
|
||
|
||
- `task_plan.md` 始终保留当前任务目标、阶段、决策和错误，建议不超过 16 KiB。
|
||
- `findings.md` 只保留仍影响当前设计和执行的事实，建议不超过 32 KiB。
|
||
- `progress.md` 只保留当前任务和最近有效里程碑，建议不超过 32 KiB。
|
||
- 超过边界时，先把原文件完整冻结到 `archive/project-history/<日期>/`，再语义压缩根文件并链接归档；禁止直接丢弃历史。
|
||
- 任务完成后不删除三文件。将计划状态收敛为完成，并保留足够信息让下一会话继续。
|
||
|
||
## 单一源与同步矩阵
|
||
|
||
- Prompt 只编辑 `agent设计规范/agent-prompt.md`；不得在 `dist/`、桌面或其他目录维护文本副本。
|
||
- 运营输入 Markdown 只编辑 `agent设计规范/templates/business-input-templates.md`；修改后使用 `tools/build_business_instruction_docx.py` 同步重建当前 DOCX，并按 Documents skill 渲染检查全部页面。macOS 的 bundled LibreOffice 若未加载中文字体，先通过 workspace dependencies 定位并设置其 `dependencies/native/poppler/poppler/etc/fonts/fonts.conf` 为 `FONTCONFIG_FILE`，不得接受方框字渲染。
|
||
- Skill 只编辑 `agent设计规范/skills/<skill>/`；发布 `.skill` 必须由当前源重新打包并逐文件核对。
|
||
- Chrome 插件只编辑 `chrome-extension/ltjt-order-assistant/`；任何代码改动都必须递增扩展版本，同步平台最低版本、mapping、测试、版本化 ZIP 和 `dist/release-manifest.json`。
|
||
- 控制面只编辑 TypeScript 源；`.build/` 由 `node --run build`（或等价包管理器命令）生成，不得手改。
|
||
- 当前交付物及哈希只由 `dist/release-manifest.json` 定义；README 只链接清单，不重复维护哈希。
|
||
- 真实验证证据进入 `archive/evidence/<日期>/`；活动 release gate 只保存当前结论并链接不可变证据。
|
||
|
||
## 历史与生成物处理
|
||
|
||
- 旧版本、旧交接、旧发布说明和完成的计划按日期移动到相应 `archive/` 分类，并更新该日期 README。
|
||
- 可重建编译产物、完全相同的别名包、`.DS_Store`、日志和临时输出不进入历史上下文；确认无唯一信息后清理。
|
||
- 不把桌面作为当前源或发布源。桌面只允许用户主动需要的临时交付副本，项目内 `dist/` 才是当前交付位置。
|
||
- 移动前必须做引用扫描；移动后必须修复活动链接。归档内部允许保留原始历史措辞，但归档 README 必须声明其非当前规则。
|
||
|
||
## 验证
|
||
|
||
文件或目录调整后至少运行：
|
||
|
||
```bash
|
||
node --run check:repo
|
||
node --run check
|
||
node --run test:control-plane
|
||
node --run test:legacy
|
||
node --run build
|
||
```
|
||
|
||
涉及 Skill 时执行官方 Skill 校验和包/源码逐文件比对；涉及 DOCX 时按 Documents skill 完成 render → 全页 PNG 检查；涉及插件时校验版本化 ZIP 与源码逐文件一致。真实 ERP 写入、部署、重启和外部发送仍需用户另行明确授权。
|