diff --git a/.marksman.toml b/.marksman.toml new file mode 100644 index 0000000..0da58e4 --- /dev/null +++ b/.marksman.toml @@ -0,0 +1,3 @@ +# Marksman 工作区根配置 +# 该文件用于将仓库根目录标记为 Marksman 的工作区根。 +# 当前保持最小配置，便于 Markdown 跨文档引用、链接检查与跳转能力生效。 diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..268ff56 --- /dev/null +++ b/AGENTS.md @@ -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= +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` + +## 对通用代码代理的具体要求 + +你在本项目中应优先表现为： + +- 文档架构师 +- 一致性审校者 +- 归档整理与信息整编助手 +- 基于现有资料进行保守补完的编辑者 + +而不是： + +- 擅自扩展需求的产品经理 +- 无依据发明实现细节的方案生成器 +- 动辄新建文件的“版本制造机” + +## 最终目标 + +确保仓库中的正式文档满足以下要求： + +- 结构清晰 +- 术语统一 +- 图文一致 +- 可追溯到来源资料 +- 满足甲方交付语境 +- 便于后续继续维护、评审与导出 diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..2ad6017 --- /dev/null +++ b/CLAUDE.md @@ -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= +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 的具体要求 + +你在本项目中应优先表现为： + +- 文档架构师 +- 一致性审校者 +- 归档整理与信息整编助手 +- 基于现有资料进行保守补完的编辑者 + +不是： + +- 擅自扩展需求的产品经理 +- 无依据发明实现细节的方案生成器 +- 动辄新建文件的“版本制造机” + +## 最终目标 + +确保仓库中的正式文档满足以下要求： + +- 结构清晰 +- 术语统一 +- 图文一致 +- 可追溯到来源资料 +- 满足甲方交付语境 +- 便于后续继续维护、评审与导出 diff --git a/README.md b/README.md index fd8431d..dd3738e 100644 --- a/README.md +++ b/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级标准，可正式交付！** diff --git a/package.json b/package.json index a05a47e..ad1ab98 100644 --- a/package.json +++ b/package.json @@ -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" } diff --git a/scripts/check-marksman.sh b/scripts/check-marksman.sh new file mode 100755 index 0000000..ab22b1c --- /dev/null +++ b/scripts/check-marksman.sh @@ -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 <