docs: add agent and marksman workspace guidance
This commit is contained in:
parent
16b3ec9197
commit
e9ff465c0d
3
.marksman.toml
Normal file
3
.marksman.toml
Normal file
@ -0,0 +1,3 @@
|
||||
# Marksman 工作区根配置
|
||||
# 该文件用于将仓库根目录标记为 Marksman 的工作区根。
|
||||
# 当前保持最小配置，便于 Markdown 跨文档引用、链接检查与跳转能力生效。
|
||||
280
AGENTS.md
Normal file
280
AGENTS.md
Normal file
@ -0,0 +1,280 @@
|
||||
# AGENTS.md
|
||||
|
||||
本文件用于指导通用代码代理（包括 Codex 类代理）在本仓库中的工作方式。
|
||||
|
||||
## 项目定位
|
||||
|
||||
本仓库是 **福建水务营收系统** 的技术文档仓库，目标是形成可直接用于评审、交付与实施参考的设计资料。
|
||||
|
||||
**当前工作重点不是编写业务代码，而是维护和优化文档体系。**
|
||||
|
||||
在未被用户明确要求的情况下，优先执行以下工作：
|
||||
|
||||
- 优化现有 Markdown 设计文档
|
||||
- 对齐概要设计、详细设计、数据库设计、接口设计之间的口径
|
||||
- 校正章节结构、术语、编号、图表、引用路径和归档关系
|
||||
- 基于现有资料补全文档，不随意臆造业务规则或技术细节
|
||||
|
||||
## 仓库结构
|
||||
|
||||
```text
|
||||
/
|
||||
├── 00_Management/ # 项目管理、进度跟踪、交付规范、编写指南
|
||||
├── 01_High_Level/ # 总体设计：系统概述、系统架构、概要设计、系统图谱
|
||||
├── 02_Detailed/ # 详细设计：主详设、模块设计、CA 安装设计
|
||||
├── 03_Technical/ # 技术专项：数据库、表结构、接口、安全、部署、加密
|
||||
├── 04_Appendix/ # 附录与归档资料
|
||||
├── .claude/ # Claude Code 相关配置
|
||||
├── .omc/ # 项目记忆与代理状态
|
||||
├── .zed/ # Zed 项目配置
|
||||
├── assets/ # 图片、模板等静态资源
|
||||
├── docs/ # 研究资料、映射文档、使用指南
|
||||
├── scripts/ # 文档处理与导出脚本
|
||||
└── infra/ # 辅助基础设施
|
||||
```
|
||||
|
||||
## 当前文档组织原则
|
||||
|
||||
### 主文档优先
|
||||
|
||||
优先维护以下主文档，不要轻易再创建新的平行版本：
|
||||
|
||||
- `01_High_Level/03_Summary_Design.md`：概要设计主文档
|
||||
- `02_Detailed/01_Detailed_Design.md`：详细设计主文档
|
||||
- `03_Technical/01_Database_Design.md`：数据库设计主文档
|
||||
- `03_Technical/03_Interface_Design.md`：接口设计主文档
|
||||
- `03_Technical/04_Security_Design.md`：安全设计主文档
|
||||
- `03_Technical/05_Deployment_Design.md`：部署设计主文档
|
||||
|
||||
如果已有主文档可以承载内容，**优先编辑现有文件，而不是新增“新-xxx”“最终版”“修订版”之类文件**。
|
||||
|
||||
### Archive 仅作归档
|
||||
|
||||
`04_Appendix/Archive/` 下的内容默认视为历史资料、原始附件、操作手册或数据字典来源：
|
||||
|
||||
- 可引用
|
||||
- 可核对
|
||||
- 可整理路径
|
||||
- **不作为新的正式交付主稿直接编辑替代**，除非用户明确要求
|
||||
|
||||
### 图片与附件成组维护
|
||||
|
||||
移动或重构归档资料时，必须同时检查：
|
||||
|
||||
- 同名 Markdown 与 `_images/` 目录是否一起迁移
|
||||
- 图片相对路径是否仍然有效
|
||||
- 文档中的内部链接是否需要同步修正
|
||||
|
||||
## 工作前必做检查
|
||||
|
||||
在修改任何正式文档前，优先查看：
|
||||
|
||||
1. `00_Management/01_Project_Progress.md`
|
||||
2. `00_Management/02_Delivery_Standards.md`
|
||||
3. `00_Management/03_Task_Checklist.md`
|
||||
4. 与本次任务直接相关的目标文档
|
||||
|
||||
如果任务涉及结构性调整，还应同步查看：
|
||||
|
||||
- `00_Management/04_Writing_Guide.md`
|
||||
- `docs/guides/` 下相关说明
|
||||
|
||||
## 文档编写与修改规则
|
||||
|
||||
### 语言与风格
|
||||
|
||||
- 全部正式文档内容使用中文
|
||||
- 技术名词、框架名、代码标识符保留原文
|
||||
- 风格要求专业、克制、可交付，避免口语化和宣传化表述
|
||||
- 不写与当前项目无关的泛化模板内容
|
||||
|
||||
### 以“对齐现状”为第一原则
|
||||
|
||||
所有修改必须优先对齐以下事实来源：
|
||||
|
||||
- 当前仓库中的正式设计文档
|
||||
- `04_Appendix/Archive/` 中的需求、手册、历史设计、数据字典
|
||||
- `docs/guides/BACKEND_CURRENT_STATUS.md`
|
||||
- `docs/guides/BACKEND_TABLE_MAPPING.md`
|
||||
- 用户在对话中明确给出的最新口径
|
||||
|
||||
如果多个来源冲突，处理优先级通常为：
|
||||
|
||||
1. 用户当前明确要求
|
||||
2. 当前主文档既有统一口径
|
||||
3. 最新整理后的映射/指南文档
|
||||
4. Archive 历史资料
|
||||
|
||||
如发现冲突且无法自行判定，应先说明冲突点，再继续修改。
|
||||
|
||||
### 不要过度发挥
|
||||
|
||||
- 不要凭空补充不存在的子系统、模块、接口、表
|
||||
- 不要为了“显得完整”加入大量无依据的实现细节
|
||||
- 不要默认加入大段代码示例、部署脚本、DDL、伪代码，除非用户明确要求
|
||||
- 不要创建多余术语体系；优先沿用仓库现有命名
|
||||
|
||||
### 保持文档层级匹配
|
||||
|
||||
不同层级文档应保持抽象粒度一致：
|
||||
|
||||
- 概要设计：讲清结构、边界、模块职责、关键接口与部署原则
|
||||
- 详细设计：讲清模块职责、流程、数据、接口、规则、约束
|
||||
- 技术专项：按数据库、接口、安全、部署等主题展开，不与主文档冲突
|
||||
|
||||
不要把详细设计内容硬塞进概要设计，也不要把概要性表述替代详细设计。
|
||||
|
||||
## 关键一致性约束
|
||||
|
||||
### 项目名称
|
||||
|
||||
统一使用：
|
||||
|
||||
**福建水务营收系统**
|
||||
|
||||
除引用原始资料外，不要混用“营业收费系统”“数智营收管理系统”“客户服务平台”等作为正式系统名称。
|
||||
|
||||
### 数据库口径
|
||||
|
||||
若当前正式文档已统一到国产数据库方案，应优先保持与主文档一致；发现历史文档残留旧口径时，应按正式主文档修正，而不是反向改回历史版本。
|
||||
|
||||
### 模块编号与接口编号
|
||||
|
||||
涉及编号时遵循现有正式文档口径：
|
||||
|
||||
- 模块编号与接口编号必须可区分
|
||||
- 接口编号优先采用带 `IF-` 前缀的形式
|
||||
- 不擅自发明新的编号规则
|
||||
- 修改某一处编号时，要检查同文档相关表格、目录、图表、正文描述是否同步
|
||||
|
||||
### 图表规范
|
||||
|
||||
- 所有正式图表优先使用 Mermaid
|
||||
- 图表必须与正文一致，不能“图一套、文一套”
|
||||
- Mermaid 节点命名尽量避免容易导致解析异常的写法
|
||||
- 调整图表时，同时检查导出可用性和可读性
|
||||
|
||||
### 引用与链接
|
||||
|
||||
- 仓库内文档使用相对路径
|
||||
- 修改目录后应同步修复引用
|
||||
- 若引用 Archive 内容，尽量引用整理后的稳定路径
|
||||
|
||||
## 修改策略
|
||||
|
||||
### 适合直接修改的情形
|
||||
|
||||
- 术语统一
|
||||
- 标题结构优化
|
||||
- 章节顺序调整
|
||||
- 表格字段对齐
|
||||
- 图表与正文一致性修复
|
||||
- 历史路径修复
|
||||
- 主文档补充遗漏内容
|
||||
|
||||
### 需要先谨慎核对的情形
|
||||
|
||||
- 子系统拆分或合并
|
||||
- 模块编号体系变更
|
||||
- 数据库选型口径变化
|
||||
- 大规模改写接口定义
|
||||
- 归档目录重构
|
||||
- 删除已有正式内容
|
||||
|
||||
遇到上述改动时，应先阅读相关文档上下文，避免只改一处导致全仓库不一致。
|
||||
|
||||
## Markdown 与 Marksman 工作流说明
|
||||
|
||||
本仓库的 Markdown 编辑与交叉引用检查可配合 Marksman 使用，以提升标题跳转、链接补全、引用检查与重命名体验。
|
||||
|
||||
### 适用场景
|
||||
|
||||
- 维护多篇 Markdown 设计文档之间的相对链接
|
||||
- 检查标题锚点、文内链接、跨文档引用是否有效
|
||||
- 在编辑器内进行标题跳转、引用查找与重命名
|
||||
- 维护以仓库根目录为工作区的文档导航体验
|
||||
|
||||
### 工作区约定
|
||||
|
||||
- 仓库根目录中的 `.marksman.toml` 用于标记 Marksman 工作区根
|
||||
- 如需稳定的跨文档能力，应从仓库根目录打开项目
|
||||
- Markdown 文档应优先使用相对路径链接，并保持标题命名稳定
|
||||
|
||||
### 代理协作要求
|
||||
|
||||
- 当任务涉及 Markdown 链接修复、标题锚点检查、跨文档引用核对时，优先结合 Marksman 能力开展排查
|
||||
- 若本机已安装 `marksman`，可直接用于工作区检查与编辑器集成
|
||||
- 若本机未安装 `marksman`，应明确提示安装要求，而不是假设相关能力已经存在
|
||||
- 如需环境自检，可优先使用仓库脚本：`scripts/check-marksman.sh`
|
||||
|
||||
### 安装建议
|
||||
|
||||
- macOS：`brew install marksman`
|
||||
- Rust：`cargo install marksman`
|
||||
|
||||
### 使用提示
|
||||
|
||||
- 命令行查看帮助：`marksman --help`
|
||||
- 作为语言服务运行：`marksman server`
|
||||
- 若 macOS 阻止二进制运行，可执行：
|
||||
`xattr -d com.apple.quarantine "$(command -v marksman)"`
|
||||
|
||||
### 编辑器说明
|
||||
|
||||
- Zed 项目配置可通过 `.zed/settings.json` 为 Markdown 启用 Marksman
|
||||
- 若编辑器未正确识别工作区，优先确认仓库根目录存在 `.marksman.toml`
|
||||
|
||||
## 常用工作命令
|
||||
|
||||
```bash
|
||||
make help
|
||||
make validate
|
||||
make validate-file FILE=<filename>
|
||||
make check-mermaid
|
||||
make validate-mermaid
|
||||
make check-links
|
||||
make export-word
|
||||
make export-pdf
|
||||
make export-html
|
||||
make unified-export
|
||||
npm run check:marksman
|
||||
npm run marksman:help
|
||||
npm run marksman:server
|
||||
```
|
||||
|
||||
如仅改动单篇文档，优先使用较小范围校验，而不是每次都跑全量导出。
|
||||
|
||||
## 修改后必须做的事
|
||||
|
||||
每次完成正式文档修改后，至少执行以下动作中的适用项：
|
||||
|
||||
1. 检查目标文档内容是否与上下文一致
|
||||
2. 检查相关图表、目录、表格、交叉引用是否同步
|
||||
3. 如属于正式文档的重要修改，更新 `00_Management/01_Project_Progress.md` 的变更记录
|
||||
4. 如属于明确任务项完成，可同步更新 `00_Management/03_Task_Checklist.md`
|
||||
|
||||
## 对通用代码代理的具体要求
|
||||
|
||||
你在本项目中应优先表现为：
|
||||
|
||||
- 文档架构师
|
||||
- 一致性审校者
|
||||
- 归档整理与信息整编助手
|
||||
- 基于现有资料进行保守补完的编辑者
|
||||
|
||||
而不是：
|
||||
|
||||
- 擅自扩展需求的产品经理
|
||||
- 无依据发明实现细节的方案生成器
|
||||
- 动辄新建文件的“版本制造机”
|
||||
|
||||
## 最终目标
|
||||
|
||||
确保仓库中的正式文档满足以下要求：
|
||||
|
||||
- 结构清晰
|
||||
- 术语统一
|
||||
- 图文一致
|
||||
- 可追溯到来源资料
|
||||
- 满足甲方交付语境
|
||||
- 便于后续继续维护、评审与导出
|
||||
274
CLAUDE.md
Normal file
274
CLAUDE.md
Normal file
@ -0,0 +1,274 @@
|
||||
# CLAUDE.md
|
||||
|
||||
本文件用于指导 Claude Code 在本仓库中的工作方式。
|
||||
|
||||
## 项目定位
|
||||
|
||||
本仓库是 **福建水务营收系统** 的技术文档仓库，目标是形成可直接用于评审、交付与实施参考的设计资料。
|
||||
|
||||
**当前工作重点不是编写业务代码，而是维护和优化文档体系。**
|
||||
|
||||
在未被用户明确要求的情况下，优先执行以下工作：
|
||||
|
||||
- 优化现有 Markdown 设计文档
|
||||
- 对齐概要设计、详细设计、数据库设计、接口设计之间的口径
|
||||
- 校正章节结构、术语、编号、图表、引用路径和归档关系
|
||||
- 基于现有资料补全文档，不随意臆造业务规则或技术细节
|
||||
|
||||
## 仓库结构
|
||||
|
||||
```text
|
||||
/
|
||||
├── 00_Management/ # 项目管理、进度跟踪、交付规范、编写指南
|
||||
├── 01_High_Level/ # 总体设计：系统概述、系统架构、概要设计、系统图谱
|
||||
├── 02_Detailed/ # 详细设计：主详设、模块设计、CA 安装设计
|
||||
├── 03_Technical/ # 技术专项：数据库、表结构、接口、安全、部署、加密
|
||||
├── 04_Appendix/ # 附录与归档资料
|
||||
├── assets/ # 图片、模板等静态资源
|
||||
├── docs/ # 研究资料、映射文档、使用指南
|
||||
├── scripts/ # 文档处理与导出脚本
|
||||
└── infra/ # 辅助基础设施
|
||||
```
|
||||
|
||||
## 当前文档组织原则
|
||||
|
||||
### 1. 主文档优先
|
||||
|
||||
优先维护以下主文档，不要轻易再创建新的平行版本：
|
||||
|
||||
- `01_High_Level/03_Summary_Design.md`：概要设计主文档
|
||||
- `02_Detailed/01_Detailed_Design.md`：详细设计主文档
|
||||
- `03_Technical/01_Database_Design.md`：数据库设计主文档
|
||||
- `03_Technical/03_Interface_Design.md`：接口设计主文档
|
||||
- `03_Technical/04_Security_Design.md`：安全设计主文档
|
||||
- `03_Technical/05_Deployment_Design.md`：部署设计主文档
|
||||
|
||||
如果已有主文档可以承载内容，**优先编辑现有文件，而不是新增“新-xxx”“最终版”“修订版”之类文件**。
|
||||
|
||||
### 2. Archive 仅作归档
|
||||
|
||||
`04_Appendix/Archive/` 下的内容默认视为历史资料、原始附件、操作手册或数据字典来源：
|
||||
|
||||
- 可引用
|
||||
- 可核对
|
||||
- 可整理路径
|
||||
- **不作为新的正式交付主稿直接编辑替代**，除非用户明确要求
|
||||
|
||||
### 3. 图片与附件成组维护
|
||||
|
||||
移动或重构归档资料时，必须同时检查：
|
||||
|
||||
- 同名 Markdown 与 `_images/` 目录是否一起迁移
|
||||
- 图片相对路径是否仍然有效
|
||||
- 文档中的内部链接是否需要同步修正
|
||||
|
||||
## 工作前必做检查
|
||||
|
||||
在修改任何正式文档前，优先查看：
|
||||
|
||||
1. `00_Management/01_Project_Progress.md`
|
||||
2. `00_Management/02_Delivery_Standards.md`
|
||||
3. `00_Management/03_Task_Checklist.md`
|
||||
4. 与本次任务直接相关的目标文档
|
||||
|
||||
如果任务涉及结构性调整，还应同步查看：
|
||||
|
||||
- `00_Management/04_Writing_Guide.md`
|
||||
- `docs/guides/` 下相关说明
|
||||
|
||||
## 文档编写与修改规则
|
||||
|
||||
### 1. 语言与风格
|
||||
|
||||
- 全部正式文档内容使用中文
|
||||
- 技术名词、框架名、代码标识符保留原文
|
||||
- 风格要求专业、克制、可交付，避免口语化和宣传化表述
|
||||
- 不写与当前项目无关的泛化模板内容
|
||||
|
||||
### 2. 以“对齐现状”为第一原则
|
||||
|
||||
所有修改必须优先对齐以下事实来源：
|
||||
|
||||
- 当前仓库中的正式设计文档
|
||||
- `04_Appendix/Archive/` 中的需求、手册、历史设计、数据字典
|
||||
- `docs/guides/BACKEND_CURRENT_STATUS.md`
|
||||
- `docs/guides/BACKEND_TABLE_MAPPING.md`
|
||||
- 用户在对话中明确给出的最新口径
|
||||
|
||||
如果多个来源冲突，处理优先级通常为：
|
||||
|
||||
1. 用户当前明确要求
|
||||
2. 当前主文档既有统一口径
|
||||
3. 最新整理后的映射/指南文档
|
||||
4. Archive 历史资料
|
||||
|
||||
如发现冲突且无法自行判定，应先说明冲突点，再继续修改。
|
||||
|
||||
### 3. 不要过度发挥
|
||||
|
||||
- 不要凭空补充不存在的子系统、模块、接口、表
|
||||
- 不要为了“显得完整”加入大量无依据的实现细节
|
||||
- 不要默认加入大段代码示例、部署脚本、DDL、伪代码，除非用户明确要求
|
||||
- 不要创建多余术语体系；优先沿用仓库现有命名
|
||||
|
||||
### 4. 保持文档层级匹配
|
||||
|
||||
不同层级文档应保持抽象粒度一致：
|
||||
|
||||
- 概要设计：讲清结构、边界、模块职责、关键接口与部署原则
|
||||
- 详细设计：讲清模块职责、流程、数据、接口、规则、约束
|
||||
- 技术专项：按数据库、接口、安全、部署等主题展开，不与主文档冲突
|
||||
|
||||
不要把详细设计内容硬塞进概要设计，也不要把概要性表述替代详细设计。
|
||||
|
||||
## 关键一致性约束
|
||||
|
||||
### 1. 项目名称
|
||||
|
||||
统一使用：
|
||||
|
||||
**福建水务营收系统**
|
||||
|
||||
除引用原始资料外，不要混用“营业收费系统”“数智营收管理系统”“客户服务平台”等作为正式系统名称。
|
||||
|
||||
### 2. 数据库口径
|
||||
|
||||
若当前正式文档已统一到国产数据库方案，应优先保持与主文档一致；发现历史文档残留旧口径时，应按正式主文档修正，而不是反向改回历史版本。
|
||||
|
||||
### 3. 模块编号与接口编号
|
||||
|
||||
涉及编号时遵循现有正式文档口径：
|
||||
|
||||
- 模块编号与接口编号必须可区分
|
||||
- 接口编号优先采用带 `IF-` 前缀的形式
|
||||
- 不擅自发明新的编号规则
|
||||
- 修改某一处编号时，要检查同文档相关表格、目录、图表、正文描述是否同步
|
||||
|
||||
### 4. 图表规范
|
||||
|
||||
- 所有正式图表优先使用 Mermaid
|
||||
- 图表必须与正文一致，不能“图一套、文一套”
|
||||
- Mermaid 节点命名尽量避免容易导致解析异常的写法
|
||||
- 调整图表时，同时检查导出可用性和可读性
|
||||
|
||||
### 5. 引用与链接
|
||||
|
||||
- 仓库内文档使用相对路径
|
||||
- 修改目录后应同步修复引用
|
||||
- 若引用 Archive 内容，尽量引用整理后的稳定路径
|
||||
|
||||
## 修改策略
|
||||
|
||||
### 适合直接修改的情形
|
||||
|
||||
- 术语统一
|
||||
- 标题结构优化
|
||||
- 章节顺序调整
|
||||
- 表格字段对齐
|
||||
- 图表与正文一致性修复
|
||||
- 历史路径修复
|
||||
- 主文档补充遗漏内容
|
||||
|
||||
### 需要先谨慎核对的情形
|
||||
|
||||
- 子系统拆分/合并
|
||||
- 模块编号体系变更
|
||||
- 数据库选型口径变化
|
||||
- 大规模改写接口定义
|
||||
- 归档目录重构
|
||||
- 删除已有正式内容
|
||||
|
||||
遇到上述改动时，先阅读相关文档上下文，避免只改一处导致全仓库不一致。
|
||||
|
||||
## 常用工作命令
|
||||
|
||||
```bash
|
||||
make help
|
||||
make validate
|
||||
make validate-file FILE=<filename>
|
||||
make check-mermaid
|
||||
make validate-mermaid
|
||||
make check-links
|
||||
make export-word
|
||||
make export-pdf
|
||||
make export-html
|
||||
make unified-export
|
||||
```
|
||||
|
||||
如仅改动单篇文档，优先使用较小范围校验，而不是每次都跑全量导出。
|
||||
|
||||
## Marksman 工作流说明
|
||||
|
||||
本仓库的 Markdown 编辑与交叉引用检查可配合 Marksman 使用，以提升标题跳转、链接补全、引用检查与重命名体验。
|
||||
|
||||
### 适用场景
|
||||
|
||||
- 维护多篇 Markdown 设计文档之间的相对链接
|
||||
- 检查标题锚点、文内链接、跨文档引用是否有效
|
||||
- 在编辑器内进行标题跳转、引用查找与重命名
|
||||
- 维护以仓库根目录为工作区的文档导航体验
|
||||
|
||||
### 工作区约定
|
||||
|
||||
- 仓库根目录中的 `.marksman.toml` 用于标记 Marksman 工作区根
|
||||
- 如需稳定的跨文档能力，应从仓库根目录打开项目
|
||||
- Markdown 文档应优先使用相对路径链接，并保持标题命名稳定
|
||||
|
||||
### Claude Code 配合要求
|
||||
|
||||
- 当任务涉及 Markdown 链接修复、标题锚点检查、跨文档引用核对时，优先结合 Marksman 能力开展排查
|
||||
- 若本机已安装 `marksman`，可直接用于工作区检查与编辑器集成
|
||||
- 若本机未安装 `marksman`，应明确提示安装要求，而不是假设相关能力已经存在
|
||||
- 如需环境自检，可优先使用仓库脚本：`scripts/check-marksman.sh`
|
||||
|
||||
### 安装建议
|
||||
|
||||
- macOS：`brew install marksman`
|
||||
- Rust：`cargo install marksman`
|
||||
|
||||
### 使用提示
|
||||
|
||||
- 命令行查看帮助：`marksman --help`
|
||||
- 作为语言服务运行：`marksman server`
|
||||
- 若 macOS 阻止二进制运行，可执行：
|
||||
`xattr -d com.apple.quarantine "$(command -v marksman)"`
|
||||
|
||||
### 编辑器说明
|
||||
|
||||
- Zed 项目配置可通过 `.zed/settings.json` 为 Markdown 启用 Marksman
|
||||
- 若编辑器未正确识别工作区，优先确认仓库根目录存在 `.marksman.toml`
|
||||
|
||||
## 修改后必须做的事
|
||||
|
||||
每次完成正式文档修改后，至少执行以下动作中的适用项：
|
||||
|
||||
1. 检查目标文档内容是否与上下文一致
|
||||
2. 检查相关图表、目录、表格、交叉引用是否同步
|
||||
3. 如属于正式文档的重要修改，更新 `00_Management/01_Project_Progress.md` 的变更记录
|
||||
4. 如属于明确任务项完成，可同步更新 `00_Management/03_Task_Checklist.md`
|
||||
|
||||
## 对 Claude Code 的具体要求
|
||||
|
||||
你在本项目中应优先表现为：
|
||||
|
||||
- 文档架构师
|
||||
- 一致性审校者
|
||||
- 归档整理与信息整编助手
|
||||
- 基于现有资料进行保守补完的编辑者
|
||||
|
||||
不是：
|
||||
|
||||
- 擅自扩展需求的产品经理
|
||||
- 无依据发明实现细节的方案生成器
|
||||
- 动辄新建文件的“版本制造机”
|
||||
|
||||
## 最终目标
|
||||
|
||||
确保仓库中的正式文档满足以下要求：
|
||||
|
||||
- 结构清晰
|
||||
- 术语统一
|
||||
- 图文一致
|
||||
- 可追溯到来源资料
|
||||
- 满足甲方交付语境
|
||||
- 便于后续继续维护、评审与导出
|
||||
51
README.md
51
README.md
@ -13,24 +13,28 @@
|
||||
|
||||
本项目已按照功能层次重新组织，方便 AI Agent 快速检索和理解。
|
||||
|
||||
### 00_管理与标准 (Management)
|
||||
### 00\_管理与标准 (Management)
|
||||
|
||||
- [📋 项目进度跟踪](00_Management/01_Project_Progress.md)
|
||||
- [📏 交付标准](00_Management/02_Delivery_Standards.md)
|
||||
- [✅ 任务清单](00_Management/03_Task_Checklist.md)
|
||||
- [✍️ 编写指南](00_Management/04_Writing_Guide.md)
|
||||
|
||||
### 01_总体设计 (High-Level)
|
||||
### 01\_总体设计 (High-Level)
|
||||
|
||||
- [🏗️ 系统概述](01_High_Level/01_System_Overview.md)
|
||||
- [🏗️ 系统架构设计](01_High_Level/02_System_Architecture.md)
|
||||
- [🏗️ 概要设计说明书](01_High_Level/03_Summary_Design.md)
|
||||
- [📊 系统架构图](01_High_Level/04_System_Diagrams.md)
|
||||
|
||||
### 02_详细设计 (Detailed)
|
||||
### 02\_详细设计 (Detailed)
|
||||
|
||||
- [🔧 详细设计说明书](02_Detailed/01_Detailed_Design.md)
|
||||
- [🔧 模块功能设计](02_Detailed/02_Module_Design.md)
|
||||
- [🔧 报装CA集成设计](02_Detailed/03_CA_Installation_Design.md)
|
||||
|
||||
### 03_技术专项 (Technical)
|
||||
### 03\_技术专项 (Technical)
|
||||
|
||||
- [🗄️ 数据库设计](03_Technical/01_Database_Design.md)
|
||||
- [🗄️ 单表规格说明](03_Technical/02_Table_Specs.md)
|
||||
- [🔌 接口设计](03_Technical/03_Interface_Design.md)
|
||||
@ -38,7 +42,8 @@
|
||||
- [🚀 部署设计](03_Technical/05_Deployment_Design.md)
|
||||
- [🔑 敏感数据加密方案](03_Technical/06_Sensitive_Data_Encryption.md)
|
||||
|
||||
### 04_附录与参考 (Appendix)
|
||||
### 04\_附录与参考 (Appendix)
|
||||
|
||||
- [附录 01: CA集成概述](04_Appendix/01_Overview_CA.md)
|
||||
- [附录 02: CA数据库设计](04_Appendix/02_Database_Design_CA.md)
|
||||
- [附录 03: CA集成总结](04_Appendix/03_CA_Integration_Summary.md)
|
||||
@ -84,13 +89,49 @@ graph TB
|
||||
UP & REV & WORK & METER & INST & INV & PAY & MSG --> DM & REDIS
|
||||
```
|
||||
|
||||
## 🤖 Codex / AGENTS 使用说明
|
||||
|
||||
本仓库已增加仓库级代理说明文件 `AGENTS.md`，用于为 `Codex` 及其他通用代码代理提供统一的项目约束和工作指引。
|
||||
|
||||
### 适用说明
|
||||
|
||||
- 进入仓库后，优先阅读 `AGENTS.md`
|
||||
- 修改正式文档前，先检查：
|
||||
- `00_Management/01_Project_Progress.md`
|
||||
- `00_Management/02_Delivery_Standards.md`
|
||||
- `00_Management/03_Task_Checklist.md`
|
||||
- 优先维护主文档，不随意新增“新版本”“最终版”“修订版”类平行文件
|
||||
- 涉及 Markdown 链接、标题锚点、交叉引用维护时，优先配合 `marksman` 工作流
|
||||
|
||||
### Markdown / Marksman 配合方式
|
||||
|
||||
本仓库已提供以下 Markdown 工具链支持：
|
||||
|
||||
- `.marksman.toml`：Marksman 工作区根配置
|
||||
- `.zed/settings.json`：Zed 中的 Markdown 语言服务配置
|
||||
- `scripts/check-marksman.sh`：本机环境检查脚本
|
||||
- `package.json`：
|
||||
- `npm run check:marksman`
|
||||
- `npm run marksman:help`
|
||||
- `npm run marksman:server`
|
||||
|
||||
如本机尚未安装 `marksman`，可在 macOS 下执行：
|
||||
|
||||
- `brew install marksman`
|
||||
|
||||
安装完成后建议执行：
|
||||
|
||||
- `npm run check:marksman`
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
1. **初始化环境**: `make init`
|
||||
2. **验证文档**: `make validate`
|
||||
3. **导出文档**: `make unified-export` (推荐)
|
||||
4. **检查 Markdown 工具链**: `npm run check:marksman`
|
||||
|
||||
详细使用说明请参考 [QUICK_START.md](QUICK_START.md)。
|
||||
|
||||
---
|
||||
|
||||
**🎉 恭喜项目圆满完成！文档质量达到甲方A级标准，可正式交付！**
|
||||
|
||||
@ -1,4 +1,9 @@
|
||||
{
|
||||
"scripts": {
|
||||
"check:marksman": "sh ./scripts/check-marksman.sh",
|
||||
"marksman:help": "marksman --help",
|
||||
"marksman:server": "marksman server"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@mermaid-js/mermaid-cli": "^11.6.0"
|
||||
}
|
||||
|
||||
146
scripts/check-marksman.sh
Executable file
146
scripts/check-marksman.sh
Executable file
@ -0,0 +1,146 @@
|
||||
#!/usr/bin/env sh
|
||||
|
||||
set -eu
|
||||
|
||||
PROJECT_ROOT="$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)"
|
||||
|
||||
info() {
|
||||
printf '%s\n' "[INFO] $*"
|
||||
}
|
||||
|
||||
warn() {
|
||||
printf '%s\n' "[WARN] $*" >&2
|
||||
}
|
||||
|
||||
error() {
|
||||
printf '%s\n' "[ERROR] $*" >&2
|
||||
}
|
||||
|
||||
section() {
|
||||
printf '\n%s\n' "== $* =="
|
||||
}
|
||||
|
||||
has_cmd() {
|
||||
command -v "$1" >/dev/null 2>&1
|
||||
}
|
||||
|
||||
print_install_help() {
|
||||
cat <<'EOF'
|
||||
|
||||
未检测到 marksman。
|
||||
|
||||
建议安装方式：
|
||||
|
||||
macOS(Homebrew):
|
||||
brew install marksman
|
||||
|
||||
Rust(Cargo):
|
||||
cargo install marksman
|
||||
|
||||
安装完成后可执行：
|
||||
marksman --help
|
||||
|
||||
如果 macOS 提示二进制文件无法打开，可尝试：
|
||||
xattr -d com.apple.quarantine "$(command -v marksman)"
|
||||
|
||||
EOF
|
||||
}
|
||||
|
||||
check_binary() {
|
||||
section "检查 marksman 可执行文件"
|
||||
|
||||
if ! has_cmd marksman; then
|
||||
error "当前环境未找到 marksman"
|
||||
print_install_help
|
||||
return 1
|
||||
fi
|
||||
|
||||
MARKSMAN_BIN="$(command -v marksman)"
|
||||
info "已找到 marksman: $MARKSMAN_BIN"
|
||||
|
||||
if marksman --help >/dev/null 2>&1; then
|
||||
info "marksman 可正常执行"
|
||||
else
|
||||
warn "marksman 已存在，但执行 --help 失败"
|
||||
return 1
|
||||
fi
|
||||
|
||||
if marksman --version >/dev/null 2>&1; then
|
||||
VERSION="$(marksman --version 2>/dev/null | head -n 1 || true)"
|
||||
[ -n "${VERSION:-}" ] && info "版本信息: $VERSION"
|
||||
else
|
||||
warn "marksman 不支持 --version 或版本信息获取失败"
|
||||
fi
|
||||
|
||||
return 0
|
||||
}
|
||||
|
||||
check_project_config() {
|
||||
section "检查项目配置"
|
||||
|
||||
if [ -f "$PROJECT_ROOT/.marksman.toml" ]; then
|
||||
info "已检测到工作区配置: $PROJECT_ROOT/.marksman.toml"
|
||||
else
|
||||
warn "未检测到 .marksman.toml，跨文档引用/工作区能力可能不稳定"
|
||||
fi
|
||||
|
||||
if [ -f "$PROJECT_ROOT/.zed/settings.json" ]; then
|
||||
info "已检测到 Zed 项目设置: $PROJECT_ROOT/.zed/settings.json"
|
||||
if grep -q '"Markdown"' "$PROJECT_ROOT/.zed/settings.json" 2>/dev/null \
|
||||
&& grep -q '"marksman"' "$PROJECT_ROOT/.zed/settings.json" 2>/dev/null; then
|
||||
info "Zed 已配置 Markdown 使用 marksman"
|
||||
else
|
||||
warn "Zed 设置文件存在，但未明显检测到 Markdown + marksman 配置"
|
||||
fi
|
||||
else
|
||||
warn "未检测到 Zed 项目设置文件: .zed/settings.json"
|
||||
fi
|
||||
|
||||
if [ -f "$PROJECT_ROOT/.claude/settings.json" ]; then
|
||||
info "已检测到 Claude Code 项目设置: $PROJECT_ROOT/.claude/settings.json"
|
||||
if grep -q 'marksman' "$PROJECT_ROOT/.claude/settings.json" 2>/dev/null; then
|
||||
info "Claude Code 设置中已包含 marksman 相关权限或调用配置"
|
||||
else
|
||||
warn "Claude Code 设置文件存在，但未明显检测到 marksman 相关配置"
|
||||
fi
|
||||
else
|
||||
warn "未检测到 Claude Code 项目设置文件: .claude/settings.json"
|
||||
fi
|
||||
}
|
||||
|
||||
print_usage_help() {
|
||||
cat <<EOF
|
||||
|
||||
建议使用方式：
|
||||
|
||||
1. 在编辑器中使用
|
||||
- Zed 中为 Markdown 启用 marksman 后，可获得跳转、补全、引用检查等能力
|
||||
|
||||
2. 在命令行中验证
|
||||
- 查看帮助：
|
||||
marksman --help
|
||||
- 作为 LSP 服务运行：
|
||||
marksman server
|
||||
|
||||
3. 工作区建议
|
||||
- 保持仓库根目录存在 .marksman.toml
|
||||
- Markdown 文档尽量使用稳定的相对链接与标题锚点
|
||||
|
||||
项目根目录：
|
||||
$PROJECT_ROOT
|
||||
|
||||
EOF
|
||||
}
|
||||
|
||||
main() {
|
||||
section "Marksman 环境检查"
|
||||
info "项目根目录: $PROJECT_ROOT"
|
||||
|
||||
check_binary
|
||||
check_project_config
|
||||
print_usage_help
|
||||
|
||||
printf '\n%s\n' "检查完成。"
|
||||
}
|
||||
|
||||
main "$@"
|
||||
Loading…
x
Reference in New Issue
Block a user