docs: 重构 v0-local-cli-view AI-Native 总纲

.gitignore

@@ -137,3 +137,6 @@ dist
 # Vite logs files
 vite.config.js.timestamp-*
 vite.config.ts.timestamp-*
+
+# Local GraphSpec snapshots
+.graphspec/

.oxlintrc.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "env": {
+    "node": true,
+    "es6": true
+  },
+  "globals": {
+    "Bun": "readonly"
+  },
+  "ignorePatterns": [
+    ".opencode/**"
+  ],
+  "overrides": [
+    {
+      "files": ["**/*.test.ts"],
+      "globals": {
+        "test": "readonly",
+        "expect": "readonly"
+      }
+    }
+  ]
+}

README.md

@@ -19,16 +19,16 @@ GraphSpec 想做的，是把"架构态势感知"从"人脑记住项目结构"这
 
 ## 当前进度
 
-**V0.1** - 最小可用起点（规划中）
+**V0.1** - 起盘阶段（规范已立，代码仍是骨架）
 
 | 模块 | 当前状态 | 说明 |
 | --- | --- | --- |
-| CLI | 待开发 | `graphspec init` / `graphspec view` |
-| Core | 待开发 | 架构图解析、数据存储 |
-| Web | 待开发 | 本地可视化服务 |
-| 项目基建 | 已完成 | GitHub 配置、AGENTS.md、README.md |
+| CLI | 骨架占位 | 仅保留可执行入口与 hello world 级别占位输出 |
+| Core | 骨架占位 | 仅保留包入口与最小占位 API |
+| Web | 骨架占位 | 仅保留包入口与最小占位 API |
+| 项目基建 | 已完成 | GitHub 配置、AGENTS.md、README.md、OpenSpec change、workspace 骨架 |
 
-如果只看仓库现状，可以把它理解成：**基础设施已经搭好，核心功能开发即将开始。**
+如果只看仓库现状，可以把它理解成：**规范和仓库骨架已经搭好，真实功能开发还没有开始。**
 
 ## 技术栈
 
@@ -66,40 +66,41 @@ GraphSpec/
 git clone https://github.com/OuraAI/GraphSpec.git
 cd GraphSpec
 
-# 安装依赖（待 packages 初始化后可用）
+# 安装依赖
 bun install
 
-# 验证命令（待 packages 初始化后可用）
+# 验证命令
 bun test      # 运行测试
-bun lint      # 运行 lint 检查
-bun typecheck # 类型检查
+bun run lint      # 运行 lint 检查
+bun run typecheck # 类型检查
 
-# 开发模式（待实现）
-bun run dev
+# 占位入口
+bun run graphspec
 ```
 
 ## 模块说明
 
 ### CLI (`packages/cli/`)
 - **职责**: 命令行入口，用户交互
-- **命令**: `init`, `view`, `sync`
-- **依赖**: `@graphspec/core`
+- **当前状态**: 仅占位入口
+- **依赖**: `@graphspec/core`、`@graphspec/web`
 
 ### Core (`packages/core/`)
 - **职责**: 核心解析和数据处理
-- **能力**: 架构图解析、数据存储、变更检测
+- **当前状态**: 仅占位 API
 - **接口**: TypeScript API
 
 ### Web (`packages/web/`)
 - **职责**: 本地可视化服务
-- **入口**: `localhost:3000`
+- **当前状态**: 仅占位 API
 
 ## 开发路线
 
 GraphSpec 遵循 AI Native 开发模式，从最小起点开始，根据实际需求逐步扩展。
 
 ### 近期目标
-- [ ] CLI 基础框架搭建
+- [x] OpenSpec change 与实现任务拆解
+- [x] workspace / package 骨架搭建
 - [ ] `init` 命令实现
 - [ ] `view` 命令实现
 - [ ] 本地可视化页面

openspec/changes/v0-local-cli-view/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-10

openspec/changes/v0-local-cli-view/design.md

@@ -0,0 +1,183 @@
+## 上下文
+
+当前仓库已经有项目定位、OpenSpec 资产和最小 workspace 骨架，但还没有进入真实功能实现。真正的分歧不在“代码怎么写”，而在“GraphSpec 到底在维护什么”。
+
+如果把 GraphSpec 理解成一个 scanner 驱动的文件依赖图工具，后续所有设计都会自动往静态分析工具靠拢：
+
+- 主图来自扫描结果
+- 视图围绕文件树和 import/export 组织
+- AI 只是去读扫描出的结构
+
+但这和当前产品定位不符。你已经明确指出了一个更真实的使用场景：
+
+- 人看到一张整体架构图，第一眼就能明白项目大概是什么结构。
+- 点进某个模块，例如 `Auth`，看到这个模块自己的细图，而不是一堆文件树。
+- 节点之间的关系不是简单树形，而可能是“建立在……之上”“作用于……”“包含 / 被包含”“依赖 / 被依赖”这类架构关系。
+- 代码里的文件、import/export、Guard、查询、配置等，更像是这些节点与关系背后的证据。
+
+所以当前 design 的核心不是把 scanner 做清楚，而是把下面三层边界钉住：
+
+1. **图资产层**：架构图本身，是主资产。
+2. **证据层**：代码、文件树、依赖、片段、摘要，是解释与校验材料。
+3. **视图层**：人和 AI 怎么读图、下钻、查看节点相关内容。
+
+## 目标 / 非目标
+
+**Goals:**
+
+- 把 GraphSpec 收紧成“架构图主资产 + CLI 主入口 + 证据层辅助”的 AI-Native 总纲。
+- 为 Phase 1 建立最小而清晰的方向：整体架构图、模块下钻图、节点相关内容视图。
+- 明确后续 issues 该先收哪些问题，不该在总纲里直接拍板哪些模型。
+- 把 Harness 作为伴随项目演进的轨道，而不是一次性大建设。
+
+**Non-Goals:**
+
+- 不在当前 change 中给出具体 schema 字段和类型名。
+- 不在当前 change 中细化 graph edit 命令协议、graph draft 数据结构或 Skill 协议。
+- 不在当前 change 中把业务流视图与结构视图全部并入 Phase 1。
+- 不让 scanner 继续扮演主图来源。
+
+## 关键决策
+
+### 1. 架构图是主资产，不是扫描结果
+
+- 决定：GraphSpec 的事实来源是架构图资产本身，而不是扫描器跑出来的文件依赖图。
+- 原因：GraphSpec 面向的是架构视角，不是代码索引视角。整体图、模块图、节点关系这些东西，本来就不必等价于文件结构。
+- 结果：代码证据可以解释图，但不能替图做主。
+
+### 2. CLI 是主入口，数据文件是兜底入口
+
+- 决定：人和 AI 后续都应优先通过 CLI 读图、看图、校验图、逐步修改图；直接编辑数据文件只作为兜底路径存在。
+- 原因：如果没有主入口，图资产很快会在多人 / 多 Agent / 多轮对话里漂掉；CLI 是最自然的护栏入口。
+
+### 3. scanner 降级为证据层
+
+- 决定：scanner 如果存在，它的职责是发现文件、import/export、依赖痕迹、代码片段等证据，并服务于解释和校验。
+- 原因：这些信息对架构图依然有帮助，但不应该决定主图长什么样。
+- 约束：scanner 不能直接覆盖主图资产，也不能定义产品主体验。
+
+### 4. 关系体系采用多视角，不强行揉成单图
+
+- 决定：当前总纲承认至少存在三类关系视角：
+  - 架构结构关系
+  - 包含 / 被包含关系
+  - 业务流 / 调度流关系
+- 原因：用户举的 `Auth` 例子已经说明，真实架构图里的关系不是单一的“import 了谁”。
+- Phase 1 约束：
+  - 先收紧结构视图与下钻关系。
+  - 业务流视图进入后续 issue。
+
+### 5. Phase 1 的设计方向
+
+- 必须支持“整体架构图 -> 模块下钻图 -> 更细层级图”的嵌套关系。
+- 必须支持“点一个节点 -> 看到节点相关内容与最小关系上下文”。
+- 允许在节点上挂接代码证据，但代码证据不能反客为主。
+- 不要求 Phase 1 先把业务流图做完整。
+
+### 6. 当前总纲不拍板模型名称，只收问题池
+
+- 决定：当前总纲不直接定义具体类型名，也不在这里拍字段。
+- 原因：现在大家只有模糊概念，还没有真正收敛出“这些模型为什么存在、为什么应该长成这样”。
+- 结果：总纲里只保留“后续 issue 必须回答的设计问题”。
+
+## Phase 1 必须先回答的设计问题
+
+### 1. 主图资产问题
+
+- 主图资产到底是单文件、多文件，还是带索引的目录结构？
+- 它怎么表达整体图、模块图和子图？
+- 它如何支持人和 AI 共同读写？
+
+### 2. 节点问题
+
+- 节点至少需要表达哪些语义层级？
+- 节点是“模块 / 引擎 / 表 / 门禁 / 服务 / 证据容器”的哪几类组合？
+- 节点本体与节点挂载的证据材料如何区分？
+
+### 3. 关系问题
+
+- Phase 1 最少需要哪几类关系，才能支撑“整体结构 + 模块下钻”？
+- 哪些关系属于后续业务流视图，而不该提前塞进当前主图？
+- 跨图关系与图内关系如何共存？
+
+### 4. 嵌套与下钻问题
+
+- 整体图和模块子图之间是什么关系：包含、引用、镜像，还是别的？
+- 下钻时要保留哪些上下文，避免用户迷失在子图里？
+- 当一个节点在多个视角中出现时，如何保持一致性？
+
+### 5. 证据层问题
+
+- 文件树、import/export、配置片段、代码片段、摘要等证据，哪些先支持？
+- 证据是挂在节点上、关系上，还是挂在单独的证据对象上？
+- 证据如何服务于解释和校验，而不篡夺主图地位？
+
+### 6. CLI 问题
+
+- CLI 至少要承担哪些职责：初始化图工作区、读取图、浏览图、校验图、修改图。
+- 什么叫“CLI 优先、文件兜底”？
+- CLI 修改图时最小护栏是什么？
+
+## 视图层方向
+
+### 1. 架构结构视图
+
+- 首页首先回答：这个系统整体由哪些重要部分构成，它们之间大概是什么关系。
+- 它不是文件树，也不是风险分析大全。
+- 它是一张让人“一眼看懂项目大概是什么样”的总图。
+
+### 2. 模块下钻视图
+
+- 点进某个模块后，应看到这个模块自己的细图，而不是直接掉进文件树。
+- 这个细图应该保留与上层图的关联，而不是把上下文切断。
+
+### 3. 节点相关内容视图
+
+- 点一个节点后，需要看到和它有关的解释材料与最小关系上下文。
+- 这些内容可能包含：相关节点、证据、说明、关联代码痕迹。
+- 目标不是把所有代码展示出来，而是帮助理解“这个节点到底是什么、为什么在这里”。
+
+### 4. 业务流视图
+
+- 当前总纲承认它是重要方向。
+- 但它不进入 Phase 1 的已定范围。
+- 它进入后续 issue，单独讨论如何和结构视图分层。
+
+## Harness 演进原则
+
+- Harness 必须跟着项目阶段长，而不是一次性包完。
+- 当前阶段的 Harness 只需要支撑当前风险：
+  - Phase 0：仓库秩序
+  - Phase 1：图资产、CLI、节点相关内容的一致性
+  - Phase 2：graph edit 护栏与审计
+  - Phase 3：Skill 调 CLI 的稳定性
+  - Phase 4：交互复杂后再考虑 Playwright
+- 原则是：不要为了这点醋包一盘饺子。
+
+## 风险 / 权衡
+
+- [Risk] 继续把 scanner 当主线，会把产品拉回静态分析工具。 → Mitigation: 在总纲里把 scanner 明确降级为证据层。
+- [Risk] 总纲继续摆出一堆抽象模型名，会让团队误以为模型已经定了。 → Mitigation: 当前总纲只保留设计问题，不直接拍类型名和字段。
+- [Risk] 业务流视图提前并入，会让 Phase 1 再次膨胀。 → Mitigation: 当前总纲只承认它的存在，不把它收进 Phase 1 已定范围。
+- [Risk] Harness 一次性做太重，会反过来拖慢项目。 → Mitigation: 单独维护 Harness 演进轨道，按阶段增量建设。
+
+## 推进与迁移计划
+
+- 当前 change 只负责把总纲从“scanner-first”扭成“graph-asset-first”。
+- 完成这次重构后，后续应优先拆出这些 issue：
+  - 架构图主数据模型
+  - 图的嵌套与下钻机制
+  - 节点相关内容与证据层
+  - CLI 读图 / 改图入口
+  - 架构视图与浏览体验
+  - Phase 1 Harness
+- 未来如果要细化 schema、关系模型或业务流视图，必须通过独立 issue / discussion 收敛，不直接改回总纲拍板。
+
+## 设计问题池
+
+- 主图资产到底应该怎样组织。
+- 节点需要表达哪些语义层级。
+- 关系需要几种大类，哪些属于 Phase 1，哪些属于后续。
+- 嵌套图与跨图关系如何共存。
+- 图资产与证据层之间如何引用。
+- CLI 修改图时最小护栏是什么。