dsh-arch-doc 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## Unreleased
+
+- npm 包名改为 `dsh-arch-doc`：`arch-doc` 触发 npm 防抢注拦截（与既有包 `archdoc` 去连字符后撞名，403）。插件 id（cordis.patch.yml / providerName）与 GitHub 仓库名保持 `arch-doc` 不变，仅 npm 分发名变更。
+- 新增 `prepublishOnly` 钩子：npm 发布前自动运行测试门禁，防止红测试状态发包。
+
+## 0.1.2 (2026-09-02)
+
+- `.gitignore` 补充 `.tmp/` 本地临时产物与 `.env` 类密钥忽略。
+- `package.json` 补充 `repository` / `bugs` / `homepage` 元数据。
+- 新增 GitHub Actions CI（`.github/workflows/ci.yml`）：ubuntu + windows × Node 18/22 矩阵运行语法检查与契约测试。
+- 新增 `.editorconfig`（UTF-8 / LF / 2 空格基线）。
+- README 新增「排障」章节：Mermaid 本地渲染、大仓库深度控制、无 Node 降级、入口识别。
+- 新增 `examples/README.md` 与 fixtures 说明。
+
+## 0.1.1 (2026-08-16)
+
+- 文档清理：移除内部实现方案稿（arch-doc-实现文档.md），公开文档不再包含本地个人路径。
+- `PUBLISHING.md` 重写：状态更新为「已推送 GitHub、npm 包名可用」，补充 dsh-index 提交步骤与版本变更流程，检查清单勾选已达成项。
+- `README.md` 补充输出产物说明、环境要求与 License。
+- 修复 `test/arch-profile.test.mjs` 字符串字面量跨行导致的语法错误，`npm test` 11 项全部通过。
+
+## 0.1.0 (2026-08-16)
+
+- 首个版本：实现 `arch-profile.mjs` 的 probe / scan / deps / entry / all 五类确定性扫描。
+- 提供 `skills/arch-doc/SKILL.md` runbook 与 `docs/architecture-template.md` 输出模板。
+- 内置 Python / Node / Go 三个最小 fixture 与 `node --test` 契约测试。
+- 按 `dsh-data-insight` 同一标准打包（`package.json` + `cordis.patch.yml` + `plugin/index.js`）。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 duyanta123
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PUBLISHING.md

@@ -0,0 +1,98 @@
+# 发布与分发指南（PUBLISHING）
+
+本文档记录 `arch-doc` 从源码到分发的完整步骤，供维护者执行。
+
+## 当前状态
+
+- 包结构已建成（package.json / cordis.patch.yml / plugin/index.js / skills / docs / scripts / examples / test）。
+- `scripts/arch-profile.mjs` 通过 `node --check`，零依赖、无子进程。
+- `npm test`（node --test）全绿，覆盖 probe / scan / deps / entry / run-methods / output-json / skip-excluded。
+- 源码已推送 GitHub（`main` 分支），npm 包名为 `dsh-arch-doc`（原名 `arch-doc` 触发 npm 防抢注拦截——与既有包 `archdoc` 去连字符后撞名；插件 id 与 GitHub 仓库名保持 `arch-doc` 不变）。
+
+## 前置条件
+
+- 能访问 github.com 与 registry.npmjs.org 的终端（或在代理环境下执行 git push）。
+- 已登录 npm：`npm login`（需要 npm 账号 + 2FA）。
+- GitHub 账号（用于建仓库与 push）。
+
+## 步骤 1：发布到 GitHub
+
+```powershell
+# 1) 浏览器打开 https://github.com/new，仓库名 arch-doc，公开，
+#    不要勾选 "Initialize with README / .gitignore / license"（本地已有）。
+cd <你的本地路径>/arch-doc
+git remote add origin https://github.com/duyanta123/arch-doc.git
+git push -u origin main
+git tag v<version>
+git push origin v<version>
+```
+
+## 步骤 2：发布到 npm
+
+```powershell
+cd <你的本地路径>/arch-doc
+npm view dsh-arch-doc version   # 确认包名可用（应 404）
+npm login
+npm publish
+```
+
+## 步骤 3：安装到 profile（三选一）
+
+```powershell
+# npm 形态
+dsh plugin --profile web add dsh-arch-doc
+
+# GitHub 形态
+dsh plugin --profile web add github:duyanta123/arch-doc#v<version>
+
+# 本地 file: 链接（无需发布）
+# profile 的 package.json 加 "arch-doc": "file:<本地路径>/arch-doc"，
+# 并在 dsh.profile.bundles 数组加 "arch-doc"，然后 pnpm install。
+```
+
+## 步骤 4：验证
+
+1. 重启 profile，技能列表应出现 `arch-doc`。
+2. 说「用 arch-doc 分析 test/fixtures/python-app」，确认五阶段执行并产出 ARCHITECTURE.md / architecture.json / Mermaid 图。
+
+## 步骤 5：提交 dsh-index
+
+在 dsh-index 仓库的 `skills/` 下新增 `arch-doc/` 目录，包含技能索引所需的最小集合：
+
+```text
+dsh-index/
+└── skills/
+    └── arch-doc/
+        ├── SKILL.md            # 技能定义（frontmatter 含 name / description）
+        ├── package.json        # 包元数据（或 dsh-index 约定的 index 元数据）
+        ├── README.md           # 能力说明
+        └── ...
+```
+
+提交方式二选一：
+
+- `dsh submit`（如本机已安装 dsh CLI）。
+- 在 dsh-index 仓库发起 PR，按其 CONTRIBUTING 约定填写技能元数据。
+
+## 提交 dsh-index 前检查清单
+
+- [x] `package.json` 的 `files` 包含全部发布文件
+- [x] `plugin/index.js` 使用 `FileSystemSkillProvider` 且 `includeDefaultRoots: false`
+- [x] `SKILL.md` frontmatter 有 `name` 和 `description`
+- [x] `scripts/arch-profile.mjs` 零依赖、无子进程
+- [x] `npm test` 通过
+- [x] `node --check` 通过
+- [x] 输入/输出 JSON 结构稳定
+- [x] 有 `examples/` 示例输出
+- [x] 有 `README.md`、`LICENSE`、`PUBLISHING.md`
+- [x] 包名 `dsh-arch-doc` 在 npm 上可用（`arch-doc` 因与既有包 `archdoc` 撞名被防抢注拦截，2026-09-02 改名）
+- [ ] 本地 profile 安装后技能可被加载并正确输出文档
+- [ ] dsh-index PR 已提交
+
+## 本地开发循环（改技能内容后）
+
+1. 改 `skills/`、`docs/`、`scripts/` 下的文件。
+2. 本地 `file:` 链接形态下，改 `skills/` 无需重装（FileSystemSkillProvider 会 watch 技能根）。
+3. 改 `plugin/index.js` / `cordis.patch.yml` / `package.json` 后需 `pnpm install` 并重启 profile。
+4. 提交前：`node --check scripts/arch-profile.mjs`、`npm test`、`git status` 确认。
+5. 版本变更时：更新 `package.json` 的 `version` 与 `CHANGELOG.md`，打 tag 并推送。

package/README.md

@@ -0,0 +1,74 @@
+# arch-doc
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![DeepSeek Harness](https://img.shields.io/badge/DeepSeek%20Harness-plugin-4c1d95)](https://github.com/topics/dsh-plugin)
+[![dsh-index](https://img.shields.io/badge/dsh--index-arch--doc-blue)](https://dsh-index.xlings.org/packages/arch-doc/)
+[![version](https://img.shields.io/badge/version-0.1.2-green)](CHANGELOG.md)
+
+DSH 技能插件：输入代码库路径，自动生成架构文档（模块职责、依赖关系、入口点、运行方式）。
+
+## 能力
+- 项目类型 / 语言 / 构建系统识别
+- 模块划分与职责总结
+- 内部 / 外部依赖提取与 Mermaid 依赖图
+- 入口点（CLI / Web / Worker / Scheduler / Library）识别
+- 运行方式（安装 / 开发 / 构建 / 测试 / 运行 / 部署）提取
+- 输出 Markdown + JSON
+
+## 目录结构
+
+```text
+arch-doc/
+├── package.json                  # npm 包 + dsh.bundle.patch
+├── cordis.patch.yml              # DSH bundle patch
+├── plugin/index.js               # ESM 入口，注册 skills/ 为技能根
+├── skills/arch-doc/SKILL.md      # 技能 frontmatter + 阶段执行 runbook
+├── docs/                         # 输出模板 + 扫描规则
+├── scripts/arch-profile.mjs      # 零依赖 Node 脚本：probe/scan/deps/entry
+├── examples/                     # 输入/输出示例
+└── test/                         # node --test 测试 + fixtures
+```
+
+## 使用
+
+1. 安装：`dsh plugin --profile web add github:duyanta123/arch-doc#v0.1.1`
+2. 使用：对 Agent 说「用 arch-doc 分析 /path/to/repo」
+3. 本地开发：profile 的 package.json 加 `"arch-doc": "file:<本地路径>/arch-doc"`，bundles 加 `"arch-doc"`
+
+## 输出
+
+- `docs/ARCHITECTURE.md`：结构化架构文档（按 `docs/architecture-template.md` 骨架）
+- `docs/architecture.json`：机器可读的结构化结果
+- `docs/diagrams/module-dependencies.mmd`：Mermaid 模块依赖图
+
+## 环境要求
+
+- Node.js >= 18（运行 `scripts/arch-profile.mjs`；无 Node 时 runbook 自动降级为 shell 手工探测）
+
+## 脚本
+
+```bash
+node scripts/arch-profile.mjs <repo_path> --probe
+node scripts/arch-profile.mjs <repo_path> --scan --max-depth 3
+node scripts/arch-profile.mjs <repo_path> --deps
+node scripts/arch-profile.mjs <repo_path> --entry
+node scripts/arch-profile.mjs <repo_path> --all
+```
+
+## 测试
+
+```bash
+npm test
+node --check scripts/arch-profile.mjs
+```
+
+## 排障
+
+- **生成的 `ARCHITECTURE.md` 里 Mermaid 图不渲染**：`file://` 协议下浏览器直接打开时，CDN 加载的 mermaid.js 受同源策略限制无法自动渲染；用 Typora 等本地渲染编辑器打开，或把 `diagrams/module-dependencies.mmd` 内容粘到 mermaid.live 查看。`.mmd` 源文件语法本身独立有效。
+- **大仓库扫描太慢 / 输出太长**：`--max-depth 3` 起步，必要时降到 2；确认 `exclude_dirs` 覆盖了 `node_modules`、`.venv`、构建产物等大目录。
+- **无 Node 环境时**：runbook 自动降级为 shell 手工探测（`find` / `ls` / 读 `package.json` / `go.mod` / `pyproject.toml`），结论质量略降但流程完整。
+- **识别不到入口点**：先跑 `--probe` 确认项目类型识别正确；混合技术栈仓库以主语言构建文件为准（如 Go+Node 混合，以 `go.mod` 优先）。
+
+## License
+
+[MIT](./LICENSE)

package/cordis.patch.yml

@@ -0,0 +1,11 @@
+# arch-doc — DSH bundle patch.
+#
+# 当某个 profile 在 dsh.profile.bundles 中列出本包时（dsh plugin add 即完成此事），
+# dsh 启动时把本补丁打入配置树：插入本包插件行，加载 package.json 的 main
+# （plugin/index.js），将自带 skills/ 注册为技能根。
+#
+# 人设与工具不在此处重复声明——宿主 profile（web/standard）已提供文件、shell、
+# 计划模式、web 搜索、子代理等 runbook 引用的全部工具。
+- insert:
+    - id: arch-doc
+      name: arch-doc

package/docs/architecture-template.md

@@ -0,0 +1,45 @@
+# 架构文档模板
+
+固定章节顺序：
+
+# 架构文档
+
+## 1. 项目概览
+- 项目名称、一句话描述、架构风格（分层/模块化/微服务/插件化）、仓库类型（monolith/monorepo/library/microservices）。
+
+## 2. 技术栈
+- 语言、框架、构建工具、数据库/中间件（仅列能在仓库中确认的）。
+
+## 3. 目录结构
+- 代码块 tree，最多 3 层，排除 node_modules/.git/dist/build 等噪音。
+
+## 4. 模块职责
+| 模块 | 路径 | 职责 | 关键文件 |
+|---|---|---|---|
+
+## 5. 模块依赖关系
+- 内部依赖表：source -> target（kind）
+- Mermaid 图：
+
+  ```mermaid
+  graph TD
+    api --> auth
+    auth --> db
+  ```
+
+## 6. 入口点
+| 类型 | 路径 | 启动命令 | 说明 |
+|---|---|---|---|
+
+## 7. 运行方式
+| 操作 | 命令 | 工作目录 |
+|---|---|---|
+
+## 8. 关键流程
+- 1–3 条核心链路，每条 3–7 步，必须基于已识别入口与依赖。
+
+## 9. 待确认/风险点
+- 动态导入、反射调用、隐式依赖、无法确定的外部服务等。
+
+## 附录
+- 扫描范围、排除目录、脚本命令、生成时间。

package/docs/scanning-rules.md

@@ -0,0 +1,95 @@
+# arch-doc 扫描与识别规则
+
+本文档固化 `scripts/arch-profile.mjs` 的确定性规则，保证不同运行环境产出一致的事实数据。
+「硬事实」由脚本产出，「语义总结」由 LLM 补充，两者不得互相替代。
+
+## 1. 语言探测（--probe）
+
+按文件优先级识别，先到先得：
+
+| 语言 | 标识文件 |
+|---|---|
+| TypeScript | tsconfig.json / pnpm-workspace.yaml（优先于 JavaScript 判定） |
+| Python | pyproject.toml / setup.py / setup.cfg / requirements.txt / Pipfile |
+| JavaScript | package.json |
+| Go | go.mod |
+| Java | pom.xml / build.gradle / build.gradle.kts / settings.gradle |
+| Kotlin | build.gradle.kts |
+| Rust | Cargo.toml |
+| C / C++ | CMakeLists.txt / Makefile / meson.build |
+| Ruby | Gemfile / Rakefile |
+| PHP | composer.json |
+
+无标识文件时用目录结构启发式：存在 `cmd/`、`internal/`、`pkg/` 判为 Go；
+存在 `src/`、`app/`、`lib/` 时按 `*.py` 与 `*.js/*.ts` 数量比较判为 Python / TypeScript；
+否则回退 `generic`。
+
+## 2. 仓库类型判定（repo_type）
+
+| 类型 | 规则 |
+|---|---|
+| monorepo | 顶层存在 packages/、apps/、services/、microservices/ |
+| microservices | 多个顶层子目录各自含 Dockerfile / main.go / main.py / package.json / go.mod |
+| library | 顶层含 src/、lib/ 或 include/ 且无运行入口 |
+| monolith | 其余情况 |
+
+「运行入口」轻量判定：存在 main.* / server.* / app.* / worker.* / cli.* / index.*，或 bin/、cmd/ 目录，或 Dockerfile。
+
+## 3. 目录扫描
+
+- 排除目录（默认）：.git、node_modules、dist、build、__pycache__、.venv、venv、target、.idea、.vscode、.pytest_cache、.mypy_cache、coverage。
+- 深度：`--max-depth` 默认 3（1–10）。
+- 文件白名单：源码、配置、Manifest、README（按扩展名 + Makefile/Dockerfile/Rakefile/Gemfile 特殊名）。
+- 大仓库保护：文件数 >2000 时只扫前两层模块，不逐文件通读内容。
+
+## 4. 模块划分（--scan）
+
+按语言惯例取模块容器目录，其直接子目录（含源码）成为模块；容器自身若无子目录而直接含源码，则容器本身为模块：
+
+| 语言 | 模块容器 |
+|---|---|
+| Python | src/、app/、lib/，及顶层含 __init__.py 的包目录 |
+| JavaScript / TypeScript | src/、lib/、packages/、apps/ |
+| Go | cmd/、internal/、pkg/ |
+| Java / Kotlin | src/main/java/（取包名首层目录） |
+| 通用 | src/、lib/、app/、packages/ |
+
+每模块输出：name、path（posix 相对路径）、language、key_files（最多 5 个，优先 README/入口/大文件）、file_count。
+
+## 5. 依赖提取（--deps）
+
+静态文本解析，不做 AST。
+
+| 语言 | 规则 |
+|---|---|
+| Python | `from X import ...`、`import X`（X 取首个标识段） |
+| JavaScript / TypeScript | `import ... from 'X'`、`import 'X'`、`require('X')`、`import('X')` |
+| Go | 单行 `import "X"` 与 `import (...)` 块 |
+| Java / Kotlin | `import X;`（含 static） |
+
+内部依赖判定：导入路径首段命中模块名，或导入路径命中模块路径（点号归一后前缀匹配 / Go 模块路径包含匹配）。
+未命中内部模块的导入归入外部依赖，并从 Manifest（package.json / pyproject.toml / go.mod / pom.xml）补版本号。
+
+动态导入（`importlib`、`__import__`、`require(变量)`）不硬猜，只记录为风险。
+
+## 6. 入口点判定（--entry）
+
+| 类型 | 判定依据 |
+|---|---|
+| web | 内容含 uvicorn/fastapi/flask/django/express/app.listen/listen(http) 等；或 server.js/app.js/index.js/main.go/Application.java |
+| cli | bin/、cmd/ 目录；或 cli.py/cli.js；或内容含 argparse/commander/cobra/click/yargs/process.argv |
+| worker | 文件名/内容含 worker、consumer、queue、celery、bullmq |
+| scheduler | 文件名/内容含 cron、scheduler、schedule |
+| library | 无运行入口，存在 lib.rs / index.ts 导出 / setup.py 包名 |
+| unknown | 无法判断时不强行分类 |
+
+## 7. 运行方式提取（--entry）
+
+| 来源 | 提取 |
+|---|---|
+| package.json scripts | install/dev/build/test/start/deploy 等（npm install / npm run <name> / npm start） |
+| pyproject.toml | [project.scripts] 控制台命令、pip install -e .、uvicorn 开发命令 |
+| Makefile | 目标名与 make <target> |
+| Dockerfile | docker build / docker run |
+| docker-compose.yml | docker compose up / down |
+| README.md | npm run / pip install / go build / mvn 等命令仅作候选，需标注来源 |

package/examples/README.md

@@ -0,0 +1,9 @@
+# Examples
+
+| 文件 | 用途 |
+|------|------|
+| `input.json` | 调用参数样例：`repo_path` / `output_path` / `max_depth` / `exclude_dirs` / `generate_mermaid` |
+| `sample-output.md` | 生成的架构文档样例（Markdown 通道） |
+| `sample-output.json` | 生成的结构化结果样例（JSON 通道：模块 / 依赖 / 入口 / 运行方式） |
+
+`test/fixtures/` 下另有 Python / Node / Go 三个最小应用，供 `node --test` 契约测试使用：`go-app`（`cmd/server` 布局）、`node-app`（`src/server.js` + ESM）、`python-app`（`src/` 包结构 + `pyproject.toml`）。

package/examples/input.json

@@ -0,0 +1,15 @@
+{
+  "repo_path": "/path/to/my-app",
+  "output_format": "both",
+  "output_path": "/path/to/my-app/docs",
+  "max_depth": 3,
+  "exclude_dirs": [
+    ".git",
+    "node_modules",
+    "dist",
+    "build",
+    "__pycache__",
+    ".venv"
+  ],
+  "generate_mermaid": true
+}

package/examples/sample-output.json

@@ -0,0 +1,78 @@
+{
+  "project": {
+    "name": "my-app",
+    "root": "/path/to/my-app",
+    "language": "python",
+    "repo_type": "monolith",
+    "description": "示例项目",
+    "tech_stack": [
+      "python",
+      "fastapi",
+      "docker"
+    ]
+  },
+  "modules": [
+    {
+      "name": "auth",
+      "path": "src/auth",
+      "responsibility": "用户认证与权限控制",
+      "language": "python",
+      "key_files": [
+        "src/auth/service.py"
+      ]
+    }
+  ],
+  "dependencies": {
+    "internal": [
+      {
+        "source": "api",
+        "target": "auth",
+        "kind": "import",
+        "path": "src/api/router.py"
+      }
+    ],
+    "external": [
+      {
+        "name": "fastapi",
+        "version": "0.115.0",
+        "category": "web"
+      }
+    ]
+  },
+  "entry_points": [
+    {
+      "type": "web",
+      "path": "src/main.py",
+      "command": "uvicorn src.main:app --reload",
+      "description": "API 服务入口"
+    }
+  ],
+  "run_methods": [
+    {
+      "action": "install",
+      "command": "pip install -e .",
+      "workspace": "."
+    },
+    {
+      "action": "dev",
+      "command": "uvicorn src.main:app --reload",
+      "workspace": "."
+    }
+  ],
+  "key_flows": [
+    {
+      "name": "用户登录",
+      "description": "登录请求处理链路",
+      "steps": [
+        "接收请求",
+        "校验参数",
+        "调用 auth 服务",
+        "返回 token"
+      ]
+    }
+  ],
+  "directory_tree": "src/\n├── api/\n├── auth/\n└── main.py",
+  "risks": [
+    "auth 模块通过 importlib 动态加载，需人工确认"
+  ]
+}

package/examples/sample-output.md

@@ -0,0 +1,60 @@
+# 架构文档
+
+> 由 arch-doc 生成。事实数据来自脚本，语义总结由 LLM 补充并标注推断。
+
+## 1. 项目概览
+- 项目名称：my-app
+- 一句话描述：示例项目（Python FastAPI 服务）
+- 架构风格：分层
+- 仓库类型：monolith
+
+## 2. 技术栈
+- 语言：python
+- 框架：fastapi、uvicorn
+- 构建/运行：docker
+
+## 3. 目录结构
+
+```text
+src/
+├── api/
+├── auth/
+└── main.py
+```
+
+## 4. 模块职责
+| 模块 | 路径 | 职责 | 关键文件 |
+|---|---|---|---|
+| auth | src/auth | 用户认证与权限控制 | src/auth/service.py |
+
+## 5. 模块依赖关系
+- 内部依赖表：api -> auth（import）
+- Mermaid 图：
+
+```mermaid
+graph TD
+  api --> auth
+```
+
+## 6. 入口点
+| 类型 | 路径 | 启动命令 | 说明 |
+|---|---|---|---|
+| web | src/main.py | uvicorn src.main:app --reload | API 服务入口 |
+
+## 7. 运行方式
+| 操作 | 命令 | 工作目录 |
+|---|---|---|
+| install | pip install -e . | . |
+| dev | uvicorn src.main:app --reload | . |
+
+## 8. 关键流程
+- **用户登录**：接收请求 -> 校验参数 -> 调用 auth 服务 -> 返回 token
+
+## 9. 待确认/风险点
+- auth 模块通过 importlib 动态加载，需人工确认
+
+## 附录
+- 扫描范围：src/（深度 3）
+- 排除目录：.git、node_modules、dist、build、__pycache__、.venv
+- 脚本命令：node scripts/arch-profile.mjs <repo> --all
+- 生成时间：（生成时填写）

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "dsh-arch-doc",
+  "version": "0.1.2",
+  "description": "DSH arch-doc skill plugin: analyze a codebase and generate architecture documentation (module responsibilities, dependencies, entry points and run methods).",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/duyanta123/arch-doc.git"
+  },
+  "bugs": {
+    "url": "https://github.com/duyanta123/arch-doc/issues"
+  },
+  "homepage": "https://github.com/duyanta123/arch-doc#readme",
+  "scripts": {
+    "test": "node --test test/arch-profile.test.mjs",
+    "prepublishOnly": "npm test"
+  },
+  "main": "./plugin/index.js",
+  "exports": {
+    ".": "./plugin/index.js",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "files": [
+    "plugin/index.js",
+    "cordis.patch.yml",
+    "skills/",
+    "docs/",
+    "scripts/",
+    "examples/",
+    "README.md",
+    "CHANGELOG.md",
+    "PUBLISHING.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@deepseek-ai/dsh-skill-filesystem": "*"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-skill-filesystem": {
+      "optional": true
+    }
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "architecture",
+    "documentation",
+    "code-analysis",
+    "dependency-graph",
+    "skills"
+  ]
+}

package/plugin/index.js

@@ -0,0 +1,41 @@
+/**
+ * arch-doc — DSH (DeepSeek Harness) 插件入口。
+ *
+ * 复用官方 @deepseek-ai/dsh-skill-filesystem 提供者，把本包自带的 skills/
+ * 目录注册为技能根（includeDefaultRoots: false，避免与宿主 profile 的
+ * 技能根重复）。零构建：本 ESM 模块由 harness 直接加载。
+ *
+ * 本包为纯指令型技能插件：它只注入 runbook 指令，计算由宿主已提供的
+ * 文件 / shell 工具驱动的 LLM 完成；arch-profile.mjs 脚本由 runbook 指引
+ * 通过 shell 直接调用（Node 内建能力，零依赖，不 spawn 子进程）。
+ */
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { FileSystemSkillProvider } from "@deepseek-ai/dsh-skill-filesystem";
+
+export const name = "arch-doc";
+export const inject = ["skills"];
+
+const rootDir = join(dirname(fileURLToPath(import.meta.url)), "..");
+const skillsDir = join(rootDir, "skills");
+
+export function apply(ctx, config = {}) {
+  let provider;
+  ctx.skills.registerProvider((control) => {
+    provider = new FileSystemSkillProvider(ctx, control, {
+      providerName: "arch-doc",
+      includeDefaultRoots: false,
+      customSkillDirs: [skillsDir],
+      ...config,
+    });
+    return provider;
+  });
+  ctx.effect(
+    function* () {
+      yield async () => {
+        await provider?.dispose();
+      };
+    },
+    "arch-doc skill provider"
+  );
+}