chorograph

根据你的文档注释绘制的架构图。

在你平时已经会写的注释中描述你的系统。chorograph 会对其进行静态解析（无需导入，无需执行），并渲染出一个独立的 HTML 架构图，精确到每一个函数。你的代码不需要任何导入、包装器或配置。而且由于所有的引用都必须可解析，一旦发生重命名或删除，下次渲染就会报错并精确指出对应的文件和行号，因此架构图绝不会无声无息地失效（腐坏）。 ``` /** * Places an order and charges it synchronously. * @endpoint POST /orders * @writes orders-db.orders * @emits order.placed so notifications and analytics can react * @calls payments.post-charge charge at checkout, in-process for now */ export async function placeOrder(items: OrderItem[]): Promise { // your real code, untouched } ``` ``` npx chorograph render src ``` ## 快速开始 三种注释即可生成你的架构图： ``` // 1. Anchor: once, in any file. Free-standing comments are fine. /** @system Acme */ /** @domain Commerce */ /** @external Stripe in:Commerce */ // 2. Infrastructure: where it's configured. /** @database orders-db in:Commerce tech:"PostgreSQL 16" tables:orders,order_items */ export const db = createPool(process.env.ORDERS_DB_URL); /** @event order.placed in:Commerce */ // 3. Each service: top of its file. Endpoints, functions, and jobs below attach automatically. /** * Owns the order lifecycle from cart to fulfilment. * @service orders in:Commerce tech:Node.js * @consumes payment.captured marks the order paid */ ``` `npx chorograph render src` 会写入 `.chorograph/graph.json` 和 `report.html`（无网络依赖；可随时随地打开、提交、发送）。`chorograph serve src` 会在每次浏览器刷新时重新扫描。[`examples/streamline/`](examples/streamline/) 是一个完整的工作示例。 ## 语法规则 一条注释声明一个节点；注释的正文会成为节点的描述。同一条注释中的 Edge 标签用于声明连接，目标之后的文本则成为其标签（label）：即说明*为什么*连接。 | 标签 | 声明内容 | | --- | --- | | `@system` / `@domain` | 架构图的标题，一个限定的上下文（bounded context） | | `@service name` | 一个可部署的进程 | | `@endpoint POST /orders` | 一个 API 对外接口 | | `@fn` / `@job` | 重要函数 / 后台任务（名称从代码中自动推断） | | `@database name tables:a,b` | 数据库及其数据表 | | `@table` / `@cache` / `@bucket` / `@queue` | 状态存储与消息传输 | | `@event order.placed` | 具名的领域事件（domain event） | | `@external Stripe` | 非你运营的第三方 | | `@of parent` | 文件级指令：其下方的所有内容都从属于 `parent` | Edges（边）：`@calls`、`@reads`、`@writes`、`@emits`、`@consumes`、`@uses`。通过名称指定目标，在存在歧义时可使用点号修饰（如 `orders-db.orders`）。 包含关系的嵌套深度完全取决于你的设计层次：服务（service）包含 endpoint、job 及其私有基础设施；endpoint 包含实现它们的各种函数；函数又可拆分为更细的函数。父级关系来源于显式的 `in:`/`of:` 关键字、文件上下文，或文件级别的 `@of` 指令，这也正是一个服务能够分散在多个 `routes/*.ts` 文件中的实现方式。

在查看器中，所有元素始终可见，并且布局是确定性的。图例提供筛选功能，鼠标悬停时会高亮显示连接关系，点击则会打开包含声明位置 `file:line` 的详情面板，同时支持使用 `/` 键进行搜索。 ## 面向 Coding Agent 这里有一个 [agent 技能](skills/chorograph/SKILL.md)，可以教会 agent 上述语法规则，从而让架构图作为日常编写文档的“副产品”始终保持最新。你可以通过 [skills CLI](https://skills.sh) 将其安装到你的项目中： ``` npx skills add flancast90/Chorograph ``` 任何人克隆此代码库后都会自动获得它：该技能文件已被提交至 `.agents/skills/` 和 `.claude/skills/` 目录下，Cursor、Claude Code 及其他相关工具均可自动识别并应用。 ## 贡献指南 运行 `pnpm install && pnpm example`，不到一分钟你就能得到一张渲染好的架构图；`pnpm typecheck && pnpm test` 则是合并代码的把关门槛。[`CONTRIBUTING.md`](CONTRIBUTING.md) 包含了相关约定，[`AGENTS.md`](AGENTS.md) 提供了面向 agent 的版本，而 [`docs/design-principles.md`](docs/design-principles.md) 则阐述了设计品味。发版是完全自动化的：只需向 `main` 分支合并一个版本升级的 PR，CI 就会自动将其发布到 npm。 ## 许可证 [MIT](LICENSE)

标签：Git, MITM代理, SOC Prime, 云安全监控, 代码分析, 代码可视化, 凭证管理, 多模态安全, 开发工具, 暗色界面, 架构图, 自动化攻击, 静态分析