@maidang1/hataraku 0.0.3

package/docs/plan/skills-2026-02-05.md

@@ -0,0 +1,352 @@
+# Skills 加载逻辑重构计划
+
+## Skills 加载流程图
+
+![Skills 加载流程](./skills-flow.svg)
+
+上图展示了 Skills 系统的完整加载流程，包括以下关键阶段：
+
+1. **缓存检查**：首先检查是否有缓存的结果，避免重复加载
+2. **发现阶段（Discovery）**：
+   - 解析根路径（Repo/User/System/Admin 四个作用域）
+   - 使用 BFS 算法扫描目录树
+   - 将发现的技能文件映射到对应的作用域
+3. **解析阶段（Parse）**：
+   - 解析 SKILL.md 文件，提取 YAML frontmatter
+   - 解析 agents/openai.yaml 元数据文件
+   - 合并两个来源的元数据
+4. **验证阶段（Validate）**：
+   - 使用 Zod Schema 验证元数据结构
+   - 检查技能是否启用（enabled 字段）
+   - 记录验证失败的警告
+5. **结果处理**：
+   - 去重和排序（按作用域优先级和名称）
+   - 缓存结果以供后续使用
+   - 发出 loadComplete 事件
+
+## 重构目标
+
+将 skills 加载逻辑重构为更加清晰、模块化、可扩展的架构，解决以下问题：
+
+1. **配置硬编码**：`.codex`、`SKILL.md`、`agents/openai.yaml` 等都是硬编码常量
+2. **职责混乱**：`loader.ts` 同时负责文件发现、路径解析、内容解析、元数据加载
+3. **缺乏抽象层**：没有将"发现策略"、"解析策略"、"配置源"等抽象出来
+4. **错误处理粗糙**：大量 `try-catch` 且静默失败，错误信息不够详细
+5. **缺乏日志系统**：加载过程不可观测
+6. **类型安全不足**：大量使用 `any` 类型解析 YAML
+7. **扩展性差**：添加新的技能格式或元数据来源需要修改核心逻辑
+
+---
+
+## 新的目录结构
+
+```
+src/core/skills/
+├── index.ts                    # 公共 API 导出
+│
+├── core/                       # 核心类型定义
+│   ├── types.ts                # SkillMetadata、SkillScope 等核心类型
+│   ├── errors.ts               # 错误类型定义
+│   └── events.ts               # 事件类型定义
+│
+├── config/                     # 配置系统
+│   ├── index.ts                # 配置管理器
+│   ├── defaults.ts             # 默认配置
+│   └── schema.ts               # 配置 schema (Zod)
+│
+├── discovery/                  # 技能发现层
+│   ├── index.ts                # 发现协调器
+│   ├── scanner.ts              # 文件系统扫描器
+│   ├── resolver.ts             # 根路径解析器
+│   └── strategies/             # 发现策略
+│       └── file-system.ts      # 基于文件系统的发现
+│
+├── parsers/                    # 解析层
+│   ├── index.ts                # 解析器协调器
+│   ├── base.ts                 # 抽象解析器基类
+│   ├── markdown.ts             # Markdown + YAML frontmatter 解析器
+│   ├── yaml-metadata.ts        # YAML 元数据解析器
+│   └── factory.ts              # 解析器工厂
+│
+├── loaders/                    # 加载层
+│   ├── index.ts                # 加载器协调器
+│   └── skill-loader.ts         # 技能加载器实现
+│
+├── cache/                      # 缓存系统
+│   ├── index.ts                # 缓存管理器
+│   ├── memory-cache.ts          # 内存缓存实现
+│   └── interface.ts            # 缓存接口定义
+│
+├── validation/                 # 验证系统
+│   ├── index.ts                # 验证协调器
+│   ├── skill-validator.ts      # 技能数据验证器
+│   └── schema.ts               # Zod 验证 schema
+│
+├── utils/                      # 工与其他函数
+│   ├── path.ts                 # 路径处理工具
+│   ├── fs.ts                   # 文件系统工具
+│   └── logger.ts               # 日志工具
+│
+├── manager.ts                  # SkillsManager（对外主最口）
+└── types.ts                    # 向后兼容的类型导出
+```
+
+---
+
+## 重构步骤
+
+### 阶段 1：基础设施
+
+1. 创建新的目录结构
+   - `src/core/skills/core/`
+   - `src/core/skills/config/`
+   - `src/core/skills/discovery/strategies/`
+   - `src/core/skills/parsers/`
+   - `src/core/skills/loaders/`
+   - `src/core/skills/cache/`
+   - `src/core/skills/validation/`
+   - `src/core/skills/utils/`
+
+2. 实现配置系统
+   - `config/defaults.ts` - 定义默认配置（保持与现有行为一致）
+   - `config/schema.ts` - 定义 Zod 配置 schema
+   - `config/index.ts` - 配置管理器类
+
+3. 实现日志系统
+   - `utils/logger.ts` - Logger 接口和 DefaultLogger 类
+
+### 阶段 2：核心类型
+
+4. 迁移和增强类型定义
+   - `core/types.ts` - 从现有 `types.ts` 迁移，添加新字段（version、author、tags、enabled）
+   - `core/errors.ts` - 定义 SkillLoadError、SkillParseError、SkillValidationError
+   - `core/events.ts` - 定义事件类型（loadStart、loadComplete、parseComplete 等）
+
+### 阶段 3：发现层
+
+5. 实现文件系统扫描器
+   - `discovery/scanner.ts` - BFS 扫描逻辑（从 `loader.ts:discoverSkillsUnderRoot` 提取）
+
+6. 实现根路径解析器
+   - `discovery/resolver.ts` - 项目根查找和作用域解析（从 `manager.ts:resolveRoots` 提取）
+
+7. 实现发现策略
+   - `discovery/strategies/file-system.ts` - 文件系统发现策略
+
+8. 创建发现协调器
+   - `discovery/index.ts` - DiscoveryCoordinator 类
+
+### 阶段 4：解析层
+
+9. 实现解析器基类
+   - `parsers/base.ts` - 抽象 SkillParser 类
+
+10. 实现 Markdown 解析器
+    - `parsers/markdown.ts` - 解析 SKILL.md 文件（从 `loader.ts:parseSkillFile` 提取）
+
+11. 实现 YAML 元数据解析器
+    - `parsers/yaml-metadata.ts` - 解析 agents/openai.yaml（从 `loader.ts:loadSkillMetadata` 提取）
+
+12. 创建解析器工厂
+    - `parsers/factory.ts` - 根据文件类型选择解析器
+
+13. 创建解析器协调器
+    - `parsers/index.ts` - ParserCoordinator 类
+
+### 阶段 5：验证系统
+
+14. 实现 Zod 验证 schema
+    - `validation/schema.ts` - 完整的验证规则（使用 zod）
+
+15. 实现验证器
+    - `validation/skill-validator.ts` - SkillValidator 类
+
+16. 创建验证协调器
+    - `validation/index.ts` - 导出验证接口
+
+### 阶段 6：缓存系统
+
+17. 实现缓存接口
+    - `cache/interface.ts` - ICache 接口定义
+
+18. 实现内存缓存
+    - `cache/memory-cache.ts` - MemoryCache 实现（支持 TTL）
+
+19. 创建缓存管理器
+    - `cache/index.ts` - CacheManager 类
+
+### 阶段 7：加载层
+
+20. 实现技能加载器
+    - `loaders/skill-loader.ts` - 完整的加载流程（编排发现、解析、验证）
+
+21. 创建加载器协调器
+    - `loaders/index.ts` - 导出加载接口
+
+### 阶段 8：管理器重构
+
+22. 重构 SkillsManager
+    - 保持公共接口不变
+    - 内部使用新的模块化组件
+
+### 阶段 9：向后兼容
+
+23. 更新类型导出
+    - 保留 `types.ts` 作为兼容层，从新模块重新导出
+
+### 阶段 10：清理
+
+24. 删除旧文件
+    - 删除 `loader.ts`
+
+---
+
+## 关键设计要点
+
+### 配置化
+
+```typescript
+export interface SkillsConfig {
+  directories: {
+    homeDir: string;
+    userSkillsDir: string;
+    systemSkillsDir: string;
+    projectMarker: string[];
+  };
+  filenames: {
+    skillFile: string;
+    metadataDir: string;
+    metadataFile: string;
+  };
+  scanning: {
+    maxDepth: number;
+    maxDirsPerRoot: number;
+    followSymlinks: boolean[];
+  };
+  cache: {
+    enabled: boolean;
+    ttl: number;
+  };
+}
+```
+
+### 默认配置（保持向后兼容）
+
+```typescript
+export const DEFAULT_CONFIG: SkillsConfig = {
+  directories: {
+    homeDir: path.join(os.homedir(), '.codex'),
+    userSkillsDir: 'skills',
+    systemSkillsDir: 'skills/.system',
+    projectMarker: ['.git', '.codex', '.agents'],
+  },
+  filenames: {
+    skillFile: 'SKILL.md',
+    metadataDir: 'agents',
+    metadataFile: 'openai.yaml',
+  },
+  scanning: {
+    maxDepth: 6,
+    maxDirsPerRoot: 2000,
+    followSymlinks: [true, true, false, true], // Repo, User, System, Admin
+  },
+  cache: {
+    enabled: true,
+    ttl: 300000, // 5 分钟 in milliseconds
+  },
+};
+```
+
+### 公共接口（保持不变）
+
+```typescript
+class SkillsManager {
+  constructor(codexHome: string);
+  getSkillsForCwd(cwd: string, forceReload?: boolean): SkillLoadOutcome;
+  clearCache(): void;
+}
+```
+
+---
+
+## 关键文件清单
+
+### 需要创建的文件
+
+```
+src/core/skills/core/types.ts
+src/core/skills/core/errors.ts
+src/core/skills/core/events.ts
+src/core/skills/config/index.ts
+src/core/skills/config/defaults.ts
+src/core/skills/config/schema.ts
+src/core/skills/discovery/index.ts
+src/core/skills/discovery/scanner.ts
+src/core/skills/discovery/resolver.ts
+src/core/skills/discovery/strategies/file-system.ts
+src/core/skills/parsers/index.ts
+src/core/skills/parsers/base.ts
+src/core/skills/parsers/markdown.ts
+src/core/skills/parsers/yaml-metadata.ts
+src/core/skills/parsers/factory.ts
+src/core/skills/loaders/index.ts
+src/core/skills/loaders/skill-loader.ts
+src/core/skills/cache/index.ts
+src/core/skills/cache/memory-cache.ts
+src/core/skills/cache/interface.ts
+src/core/skills/validation/index.ts
+src/core/skills/validation/skill-validator.ts
+src/core/skills/validation/schema.ts
+src/core/skills/utils/path.ts
+src/core/skills/utils/fs.ts
+src/core/skills/utils/logger.ts
+```
+
+### 需要修改的文件
+
+```
+src/core/skills/manager.ts    # 重构内部实现
+src/core/skills/types.ts       # 改为兼容层
+```
+
+### 需要删除的文件
+
+```
+src/core/skills/loader.ts      # 逻辑拆分到新模块
+```
+
+### 集成点
+
+```
+src/core/agent/index.ts       # 确保 SkillsManager 兼容性
+src/core/tools/skills.ts       # 更新类型导入路径
+```
+
+---
+
+## 验证步骤
+
+1. 运行 `bun run src/index.ts` 确保应用正常启动
+2. 验证 skills 能被正确加载（包括 .codex/skills 和项目级 skills）
+3. 测试缓存机制（多次调用 `getSkillsForCwd` 应使用缓存）
+4. 测试 `forceReload` 参数（应强制重新加载）
+5. 验证元数据解析（SKILL.md + agents/openai.yaml）
+6. 验证技能依赖处理（MCP 服务器动态加载）
+
+---
+
+## 依赖说明
+
+- **js-yaml**：已存在，用于 YAML 解析
+- **zod**：可能需要添加，用于运行时类型验证
+
+### 检查 zod 是否已安装
+
+```bash
+bun pm ls zod
+```
+
+如果没有安装，需要运行：
+```bash
+bun add zod
+```

package/docs/plan/skills-flow.svg

@@ -0,0 +1,120 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 696.7125 1317.2" width="696.7125" height="1317.2" style="--bg:#1a1b26;--fg:#a9b1d6;--line:#3d59a1;--accent:#7aa2f7;--muted:#565f89;background:var(--bg)">
+<style>
+  @import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&amp;display=swap');
+  text { font-family: 'Inter', system-ui, sans-serif; }
+  svg {
+    /* Derived from --bg and --fg (overridable via --line, --accent, etc.) */
+    --_text:          var(--fg);
+    --_text-sec:      var(--muted, color-mix(in srgb, var(--fg) 60%, var(--bg)));
+    --_text-muted:    var(--muted, color-mix(in srgb, var(--fg) 40%, var(--bg)));
+    --_text-faint:    color-mix(in srgb, var(--fg) 25%, var(--bg));
+    --_line:          var(--line, color-mix(in srgb, var(--fg) 30%, var(--bg)));
+    --_arrow:         var(--accent, color-mix(in srgb, var(--fg) 50%, var(--bg)));
+    --_node-fill:     var(--surface, color-mix(in srgb, var(--fg) 3%, var(--bg)));
+    --_node-stroke:   var(--border, color-mix(in srgb, var(--fg) 20%, var(--bg)));
+    --_group-fill:    var(--bg);
+    --_group-hdr:     color-mix(in srgb, var(--fg) 5%, var(--bg));
+    --_inner-stroke:  color-mix(in srgb, var(--fg) 12%, var(--bg));
+    --_key-badge:     color-mix(in srgb, var(--fg) 10%, var(--bg));
+  }
+</style>
+<defs>
+  <marker id="arrowhead" markerWidth="8" markerHeight="4.8" refX="8" refY="2.4" orient="auto">
+    <polygon points="0 0, 8 2.4, 0 4.8" fill="var(--_arrow)" />
+  </marker>
+  <marker id="arrowhead-start" markerWidth="8" markerHeight="4.8" refX="0" refY="2.4" orient="auto-start-reverse">
+    <polygon points="8 0, 0 2.4, 8 4.8" fill="var(--_arrow)" />
+  </marker>
+</defs>
+<polyline points="304.42499999999995,76 304.42499999999995,116.00000000000001" fill="none" stroke="var(--_line)" stroke-width="0.75" marker-end="url(#arrowhead)" />
+<polyline points="272.1823923264209,168.35739232642095 272.1823923264209,229.1 77.45,229.1 77.45,1165.2" fill="none" stroke="var(--_line)" stroke-width="0.75" marker-end="url(#arrowhead)" />
+<polyline points="337.5404872345319,167.48451276546808 337.5404872345319,229.1 559.6999999999999,229.1 559.6999999999999,257.6" fill="none" stroke="var(--_line)" stroke-width="0.75" marker-end="url(#arrowhead)" />
+<polyline points="559.6999999999999,293.6 559.6999999999999,375.77500000000003" fill="none" stroke="var(--_line)" stroke-width="0.75" marker-end="url(#arrowhead)" />
+<polyline points="559.6999999999999,411.77500000000003 559.6999999999999,482.45000000000005 516.4575,482.45000000000005 516.4575,556.7" fill="none" stroke="var(--_line)" stroke-width="0.75" marker-end="url(#arrowhead)" />
+<polyline points="516.4575,592.7 516.4575,695.45" fill="none" stroke="var(--_line)" stroke-width="0.75" marker-end="url(#arrowhead)" />
+<polyline points="516.4575,731.45 516.4575,816.325" fill="none" stroke="var(--_line)" stroke-width="0.75" marker-end="url(#arrowhead)" />
+<polyline points="516.4575,852.325 516.4575,955.2 478.13749999999993,955.2" fill="none" stroke="var(--_line)" stroke-width="0.75" marker-end="url(#arrowhead)" />
+<polyline points="529.8874999999999,973.2 529.8874999999999,1013.2" fill="none" stroke="var(--_line)" stroke-width="0.75" marker-end="url(#arrowhead)" />
+<polyline points="529.8874999999999,1049.2 529.8874999999999,1089.2" fill="none" stroke="var(--_line)" stroke-width="0.75" marker-end="url(#arrowhead)" />
+<polyline points="529.8874999999999,1125.2 529.8874999999999,1165.2" fill="none" stroke="var(--_line)" stroke-width="0.75" marker-end="url(#arrowhead)" />
+<polyline points="529.8874999999999,1201.2 529.8874999999999,1259.2 498.3124999999999,1259.2" fill="none" stroke="var(--_line)" stroke-width="0.75" marker-end="url(#arrowhead)" />
+<polyline points="560.7874999999999,1241.2 560.7874999999999,1221.2 680.5,1221.2 680.5,405.61854001009897 366.96395998990107,405.61854001009897" fill="none" stroke="var(--_line)" stroke-width="0.75" marker-end="url(#arrowhead)" />
+<polyline points="278.775899683954,414.09339968395403 278.775899683954,482.45000000000005 144.6875,482.45000000000005 144.6875,695.45" fill="none" stroke="var(--_line)" stroke-width="0.75" marker-end="url(#arrowhead)" />
+<polyline points="302.822647578466,438.14014757846604 302.822647578466,482.45000000000005 287.03249999999997,482.45000000000005 287.03249999999997,510.95000000000005" fill="none" stroke="var(--_line)" stroke-width="0.75" marker-end="url(#arrowhead)" />
+<polyline points="265.31546703296704,616.732967032967 265.31546703296704,666.95 239.37,666.95 239.37,695.45" fill="none" stroke="var(--_line)" stroke-width="0.75" marker-end="url(#arrowhead)" />
+<polyline points="308.74953296703296,616.732967032967 308.74953296703296,666.95 334.695,666.95 334.695,695.45" fill="none" stroke="var(--_line)" stroke-width="0.75" marker-end="url(#arrowhead)" />
+<polyline points="144.6875,731.45 144.6875,817.0689467695031 239.41855323049688,817.0689467695031" fill="none" stroke="var(--_line)" stroke-width="0.75" marker-end="url(#arrowhead)" />
+<polyline points="239.37,731.45 239.37,801.2129042628042 255.2745957371958,801.2129042628042" fill="none" stroke="var(--_line)" stroke-width="0.75" marker-end="url(#arrowhead)" />
+<polyline points="334.695,731.45 334.695,810.1323272118129 289.71982721181286,810.1323272118129" fill="none" stroke="var(--_line)" stroke-width="0.75" marker-end="url(#arrowhead)" />
+<polyline points="305.36113187508613,842.8763681249138 305.36113187508613,908.7 592.6574999999999,908.7 592.6574999999999,955.2 581.6374999999999,955.2" fill="none" stroke="var(--_line)" stroke-width="0.75" marker-end="url(#arrowhead)" />
+<polyline points="268.03749999999997,880.2 268.03749999999997,937.2" fill="none" stroke="var(--_line)" stroke-width="0.75" marker-end="url(#arrowhead)" />
+<polyline points="268.03749999999997,973.2 268.03749999999997,1013.2" fill="none" stroke="var(--_line)" stroke-width="0.75" marker-end="url(#arrowhead)" />
+<polyline points="268.03749999999997,1049.2 268.03749999999997,1089.2" fill="none" stroke="var(--_line)" stroke-width="0.75" marker-end="url(#arrowhead)" />
+<polyline points="268.03749999999997,1125.2 268.03749999999997,1165.2" fill="none" stroke="var(--_line)" stroke-width="0.75" marker-end="url(#arrowhead)" />
+<polyline points="77.45,1201.2 77.45,1259.2 74.03499999999995,1259.2" fill="none" stroke="var(--_line)" stroke-width="0.75" marker-end="url(#arrowhead)" />
+<polyline points="268.03749999999997,1201.2 268.03749999999997,1259.2 134.03499999999997,1259.2" fill="none" stroke="var(--_line)" stroke-width="0.75" marker-end="url(#arrowhead)" />
+<rect x="58.010000000000005" y="746.45" width="38.88" height="27" rx="4" ry="4" fill="var(--bg)" stroke="var(--_inner-stroke)" stroke-width="0.5" />
+<text x="77.45" y="759.95" text-anchor="middle" dy="0.35em" font-size="11" font-weight="400" fill="var(--_text-muted)">缓存命中</text>
+<rect x="537.4" y="215.6" width="44.6" height="27" rx="4" ry="4" fill="var(--bg)" stroke="var(--_inner-stroke)" stroke-width="0.5" />
+<text x="559.6999999999999" y="229.1" text-anchor="middle" dy="0.35em" font-size="11" font-weight="400" fill="var(--_text-muted)">缓存未命中</text>
+<rect x="125.2475" y="561.2" width="38.88" height="27" rx="4" ry="4" fill="var(--bg)" stroke="var(--_inner-stroke)" stroke-width="0.5" />
+<text x="144.6875" y="574.7" text-anchor="middle" dy="0.35em" font-size="11" font-weight="400" fill="var(--_text-muted)">验证失败</text>
+<rect x="267.5925" y="468.95000000000005" width="38.88" height="27" rx="4" ry="4" fill="var(--bg)" stroke="var(--_inner-stroke)" stroke-width="0.5" />
+<text x="287.03249999999997" y="482.45000000000005" text-anchor="middle" dy="0.35em" font-size="11" font-weight="400" fill="var(--_text-muted)">验证通过</text>
+<rect x="208.49" y="653.45" width="61.760000000000005" height="27" rx="4" ry="4" fill="var(--bg)" stroke="var(--_inner-stroke)" stroke-width="0.5" />
+<text x="239.37" y="666.95" text-anchor="middle" dy="0.35em" font-size="11" font-weight="400" fill="var(--_text-muted)">disabled</text>
+<rect x="306.675" y="653.45" width="56.04" height="27" rx="4" ry="4" fill="var(--bg)" stroke="var(--_inner-stroke)" stroke-width="0.5" />
+<text x="334.695" y="666.95" text-anchor="middle" dy="0.35em" font-size="11" font-weight="400" fill="var(--_text-muted)">enabled</text>
+<rect x="581.7974999999999" y="895.2" width="21.72" height="27" rx="4" ry="4" fill="var(--bg)" stroke="var(--_inner-stroke)" stroke-width="0.5" />
+<text x="592.6574999999999" y="908.7" text-anchor="middle" dy="0.35em" font-size="11" font-weight="400" fill="var(--_text-muted)">是</text>
+<rect x="257.17749999999995" y="895.2" width="21.72" height="27" rx="4" ry="4" fill="var(--bg)" stroke="var(--_inner-stroke)" stroke-width="0.5" />
+<text x="268.03749999999997" y="908.7" text-anchor="middle" dy="0.35em" font-size="11" font-weight="400" fill="var(--_text-muted)">否</text>
+<rect x="216.92499999999995" y="40" width="175" height="36" rx="18" ry="18" fill="#e1f5e1" stroke="var(--_node-stroke)" stroke-width="0.75" />
+<polygon points="304.42499999999995,116.00000000000001 346.72499999999997,158.3 304.42499999999995,200.60000000000002 262.12499999999994,158.3" fill="#fff9c4" stroke="var(--_node-stroke)" stroke-width="0.75" />
+<rect x="40" y="1165.2" width="74.9" height="36" rx="0" ry="0" fill="var(--_node-fill)" stroke="var(--_node-stroke)" stroke-width="0.75" />
+<rect x="490.07499999999993" y="257.6" width="139.25" height="36" rx="0" ry="0" fill="var(--_node-fill)" stroke="var(--_node-stroke)" stroke-width="0.75" />
+<rect x="493.6499999999999" y="375.77500000000003" width="132.10000000000002" height="36" rx="0" ry="0" fill="#e3f2fd" stroke="var(--_node-stroke)" stroke-width="0.75" />
+<rect x="386.0575" y="556.7" width="260.8" height="36" rx="0" ry="0" fill="var(--_node-fill)" stroke="var(--_node-stroke)" stroke-width="0.75" />
+<rect x="432.53249999999997" y="695.45" width="167.85000000000002" height="36" rx="0" ry="0" fill="var(--_node-fill)" stroke="var(--_node-stroke)" stroke-width="0.75" />
+<rect x="471.85749999999996" y="816.325" width="89.2" height="36" rx="0" ry="0" fill="var(--_node-fill)" stroke="var(--_node-stroke)" stroke-width="0.75" />
+<rect x="478.13749999999993" y="937.2" width="103.5" height="36" rx="0" ry="0" fill="#fff3e0" stroke="var(--_node-stroke)" stroke-width="0.75" />
+<rect x="406.63749999999993" y="1013.2" width="246.50000000000003" height="36" rx="0" ry="0" fill="var(--_node-fill)" stroke="var(--_node-stroke)" stroke-width="0.75" />
+<rect x="403.06249999999994" y="1089.2" width="253.65" height="36" rx="0" ry="0" fill="var(--_node-fill)" stroke="var(--_node-stroke)" stroke-width="0.75" />
+<rect x="496.01249999999993" y="1165.2" width="67.75" height="36" rx="0" ry="0" fill="var(--_node-fill)" stroke="var(--_node-stroke)" stroke-width="0.75" />
+<rect x="498.3124999999999" y="1241.2" width="124.95" height="36" rx="0" ry="0" fill="#f3e5f5" stroke="var(--_node-stroke)" stroke-width="0.75" />
+<polygon points="318.6325,333.6 378.8075,393.77500000000003 318.6325,453.95000000000005 258.4575,393.77500000000003" fill="#fff9c4" stroke="var(--_node-stroke)" stroke-width="0.75" />
+<rect x="114.3875" y="695.45" width="60.6" height="36" rx="0" ry="0" fill="var(--_node-fill)" stroke="var(--_node-stroke)" stroke-width="0.75" />
+<polygon points="287.03249999999997,510.95000000000005 350.78249999999997,574.7 287.03249999999997,638.45 223.28249999999997,574.7" fill="#fff9c4" stroke="var(--_node-stroke)" stroke-width="0.75" />
+<rect x="205.495" y="695.45" width="67.75" height="36" rx="0" ry="0" fill="var(--_node-fill)" stroke="var(--_node-stroke)" stroke-width="0.75" />
+<rect x="297.245" y="695.45" width="74.9" height="36" rx="0" ry="0" fill="var(--_node-fill)" stroke="var(--_node-stroke)" stroke-width="0.75" />
+<polygon points="268.03749999999997,788.45 313.91249999999997,834.325 268.03749999999997,880.2 222.16249999999997,834.325" fill="var(--_node-fill)" stroke="var(--_node-stroke)" stroke-width="0.75" />
+<rect x="234.16249999999997" y="937.2" width="67.75" height="36" rx="0" ry="0" fill="var(--_node-fill)" stroke="var(--_node-stroke)" stroke-width="0.75" />
+<rect x="237.73749999999995" y="1013.2" width="60.6" height="36" rx="0" ry="0" fill="var(--_node-fill)" stroke="var(--_node-stroke)" stroke-width="0.75" />
+<rect x="187.68749999999994" y="1089.2" width="160.70000000000002" height="36" rx="0" ry="0" fill="var(--_node-fill)" stroke="var(--_node-stroke)" stroke-width="0.75" />
+<rect x="184.11249999999995" y="1165.2" width="167.85000000000002" height="36" rx="0" ry="0" fill="var(--_node-fill)" stroke="var(--_node-stroke)" stroke-width="0.75" />
+<rect x="74.03499999999995" y="1241.2" width="60" height="36" rx="18" ry="18" fill="#ffe1e1" stroke="var(--_node-stroke)" stroke-width="0.75" />
+<text x="304.42499999999995" y="58" text-anchor="middle" dy="0.35em" font-size="13" font-weight="500" fill="var(--_text)">用户调用 getSkillsForCwd</text>
+<text x="304.42499999999995" y="158.3" text-anchor="middle" dy="0.35em" font-size="13" font-weight="500" fill="var(--_text)">检查缓存</text>
+<text x="77.45" y="1183.2" text-anchor="middle" dy="0.35em" font-size="13" font-weight="500" fill="var(--_text)">返回缓存结果</text>
+<text x="559.6999999999999" y="275.6" text-anchor="middle" dy="0.35em" font-size="13" font-weight="500" fill="var(--_text)">发出 loadStart 事件</text>
+<text x="559.6999999999999" y="393.77500000000003" text-anchor="middle" dy="0.35em" font-size="13" font-weight="500" fill="var(--_text)">发现阶段 Discovery</text>
+<text x="516.4575" y="574.7" text-anchor="middle" dy="0.35em" font-size="13" font-weight="500" fill="var(--_text)">解析根路径&lt;br/&gt;Repo/User/System/Admin</text>
+<text x="516.4575" y="713.45" text-anchor="middle" dy="0.35em" font-size="13" font-weight="500" fill="var(--_text)">扫描技能文件&lt;br/&gt;BFS 遍历目录</text>
+<text x="516.4575" y="834.325" text-anchor="middle" dy="0.35em" font-size="13" font-weight="500" fill="var(--_text)">映射文件到作用域</text>
+<text x="529.8874999999999" y="955.2" text-anchor="middle" dy="0.35em" font-size="13" font-weight="500" fill="var(--_text)">解析阶段 Parse</text>
+<text x="529.8874999999999" y="1031.2" text-anchor="middle" dy="0.35em" font-size="13" font-weight="500" fill="var(--_text)">解析 SKILL.md&lt;br/&gt;提取 frontmatter</text>
+<text x="529.8874999999999" y="1107.2" text-anchor="middle" dy="0.35em" font-size="13" font-weight="500" fill="var(--_text)">解析 agents/openai.yaml&lt;br/&gt;加载元数据</text>
+<text x="529.8874999999999" y="1183.2" text-anchor="middle" dy="0.35em" font-size="13" font-weight="500" fill="var(--_text)">合并元数据</text>
+<text x="560.7874999999999" y="1259.2" text-anchor="middle" dy="0.35em" font-size="13" font-weight="500" fill="var(--_text)">验证阶段 Validate</text>
+<text x="318.6325" y="393.77500000000003" text-anchor="middle" dy="0.35em" font-size="13" font-weight="500" fill="var(--_text)">Schema 验证</text>
+<text x="144.6875" y="713.45" text-anchor="middle" dy="0.35em" font-size="13" font-weight="500" fill="var(--_text)">记录警告</text>
+<text x="287.03249999999997" y="574.7" text-anchor="middle" dy="0.35em" font-size="13" font-weight="500" fill="var(--_text)">检查 enabled</text>
+<text x="239.37" y="713.45" text-anchor="middle" dy="0.35em" font-size="13" font-weight="500" fill="var(--_text)">跳过该技能</text>
+<text x="334.695" y="713.45" text-anchor="middle" dy="0.35em" font-size="13" font-weight="500" fill="var(--_text)">添加到结果集</text>
+<text x="268.03749999999997" y="834.325" text-anchor="middle" dy="0.35em" font-size="13" font-weight="500" fill="var(--_text)">还有技能?</text>
+<text x="268.03749999999997" y="955.2" text-anchor="middle" dy="0.35em" font-size="13" font-weight="500" fill="var(--_text)">去重和排序</text>
+<text x="268.03749999999997" y="1031.2" text-anchor="middle" dy="0.35em" font-size="13" font-weight="500" fill="var(--_text)">缓存结果</text>
+<text x="268.03749999999997" y="1107.2" text-anchor="middle" dy="0.35em" font-size="13" font-weight="500" fill="var(--_text)">发出 loadComplete 事件</text>
+<text x="268.03749999999997" y="1183.2" text-anchor="middle" dy="0.35em" font-size="13" font-weight="500" fill="var(--_text)">返回 SkillLoadOutcome</text>
+<text x="104.03499999999995" y="1259.2" text-anchor="middle" dy="0.35em" font-size="13" font-weight="500" fill="var(--_text)">结束</text>
+</svg>

package/docs/plan/tui-readability-2026-02-06.md

@@ -0,0 +1,67 @@
+## TUI 可读性重构计划（双栏聚焦 + 摘要优先）
+
+### Summary
+当前 TUI 的主要问题是“信息层级不清 + 单列堆叠导致阅读路径断裂”。  
+我建议将现有时间线改为“双栏聚焦”并采用“摘要优先”策略，保持 Codex 常见交互节奏：右侧主对话连续、左侧工具与系统状态结构化、底部输入始终可用、确认操作始终显眼。
+
+### 现状分析（基于代码）
+1. 渲染链路是单列线性堆叠：`/Users/bytedance/codes/ai/hataraku/src/render/index.tsx` + `/Users/bytedance/codes/ai/hataraku/src/render/components/Timeline.tsx`。  
+2. 聊天消息默认全量展开，工具和确认事件是卡片/行混排，长会话时“关键状态”容易被冲掉：`/Users/bytedance/codes/ai/hataraku/src/render/components/ChatBubble.tsx`、`/Users/bytedance/codes/ai/hataraku/src/render/components/ToolCard.tsx`。  
+3. 输入/浏览模式用 `Esc` 切换，交互状态隐藏在状态栏文本里，认知成本高：`/Users/bytedance/codes/ai/hataraku/src/render/components/StatusBar.tsx`。  
+4. 事件模型缺少“展示摘要/严重级别/耗时/最新状态聚合”字段，UI 只能直接渲染原始事件：`/Users/bytedance/codes/ai/hataraku/src/render/state/events.ts`。
+
+### 产品决策（已锁定）
+1. 布局：双栏聚焦。  
+2. 信息策略：摘要优先，详情按需展开。  
+3. 保持当前 Slash 命令集合兼容（`/help /clear /model /session /init`）。
+
+### 目标交互规格（Decision Complete）
+1. 主布局改为三段式：顶部状态条 + 中部双栏主体 + 底部输入条。  
+2. 中部左栏为 `Activity`（工具、确认、MCP、错误），右栏为 `Conversation`（用户/助手消息流）。  
+3. 焦点模式从 `input|timeline` 改为 `composer|activity|conversation`，默认 `composer`。  
+4. 键位统一：`Esc` 在 `composer` 与 `activity` 间切换，`Tab` 在 `activity` 与 `conversation` 间切换，`Enter/e` 展开当前项，`i` 回到输入。  
+5. 摘要规则：  
+   - 工具事件默认单行摘要（工具名、状态、预览、耗时）。  
+   - 确认事件默认高亮且置顶 pin（直到 resolved）。  
+   - MCP/info 事件合并去噪（同 server 的重复 info 合并为最新）。  
+   - 错误事件默认展开首行，stack 按需展开。  
+6. 对话规则：  
+   - 用户消息始终全显。  
+   - 助手消息流式显示，历史消息按块折叠（超过阈值显示“... 展开”）。  
+   - “Thinking...”从独立行改为顶部/输入区状态标记，减少视觉跳动。  
+7. 输入区规则：  
+   - 始终可见。  
+   - 若有 pending confirm，输入区上方显示确认 banner，并抢占主提示（`y/n/Esc`）。  
+8. 宽度适配：`<100` 列自动退化为单栏分页（先 conversation，按键切换 activity）。
+
+### 需要修改的接口/类型（Public APIs / Interfaces）
+1. `UiMode`（`/Users/bytedance/codes/ai/hataraku/src/render/state/events.ts`）调整为 `composer | activity | conversation`。  
+2. `UiEvent` 扩展字段：`summary?: string`、`severity?: "info"|"warn"|"error"`、`startedAt?`、`endedAt?`、`pinned?`。  
+3. `addToolEvent/completeToolEvent` 增加耗时支持（通过 startedAt/endedAt 计算）。  
+4. `StatusBar` props 调整为包含焦点 pane、pending confirm 数、最近工具状态。  
+5. `Timeline` 拆分为 `ActivityPane` 和 `ConversationPane`（组件接口独立，避免互相耦合）。
+
+### 实施步骤（文件级）
+1. 在 `/Users/bytedance/codes/ai/hataraku/src/render/state/events.ts` 扩展事件模型与派生选择器（最新错误、pending confirm、active tools）。  
+2. 在 `/Users/bytedance/codes/ai/hataraku/src/render/index.tsx` 重构主布局和键盘状态机（焦点切换、窄屏降级、banner 插槽）。  
+3. 新增 `/Users/bytedance/codes/ai/hataraku/src/render/components/ActivityPane.tsx`，承接 Tool/Confirm/MCP/Error 的摘要列表与详情展开。  
+4. 新增 `/Users/bytedance/codes/ai/hataraku/src/render/components/ConversationPane.tsx`，承接 chat 流、历史折叠和流式标记。  
+5. 调整 `/Users/bytedance/codes/ai/hataraku/src/render/components/StatusBar.tsx` 为“状态摘要条”而非长提示文本。  
+6. 调整 `/Users/bytedance/codes/ai/hataraku/src/render/components/ToolCard.tsx`、`/Users/bytedance/codes/ai/hataraku/src/render/components/ConfirmCard.tsx` 为“摘要行 + 展开详情”双态组件。  
+7. 在 `/Users/bytedance/codes/ai/hataraku/src/render/theme.ts` 增加语义色 token（focus/pending/error-muted/surface），统一对比度。  
+8. 在 `/Users/bytedance/codes/ai/hataraku/src/render/commands/index.ts` 更新 `/help` 文案，匹配新键位。
+
+### 测试与验收
+1. 类型检查：`bunx tsc -p tsconfig.json --noEmit` 必须通过。  
+2. 回归脚本：`bun run test-e2e.ts` 必须通过。  
+3. 手工场景 A：连续 20+ 条对话，确认右栏对话可连续阅读，左栏不淹没。  
+4. 手工场景 B：连续 tool use + confirm，确认 pending banner 始终可见且可快速响应。  
+5. 手工场景 C：MCP 重连与错误混合事件，确认错误不会被 info 刷屏覆盖。  
+6. 手工场景 D：80 列终端下退化布局可用，键位一致。  
+7. 验收标准：用户在 5 秒内能识别“现在在做什么、是否需要确认、最近一次工具结果是什么”。
+
+### Assumptions & Defaults
+1. 不引入新 UI 依赖，继续使用 Ink + Jotai。  
+2. 不改 Agent 事件源语义，只在渲染层补充展示元数据。  
+3. 第一版不做鼠标交互，只优化键盘流。  
+4. 历史折叠阈值默认 12 行，可后续配置化。

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@maidang1/hataraku",
+  "version": "0.0.3",
+  "module": "src/index.ts",
+  "bin": {
+    "hataraku": "./src/index.ts"
+  },
+  "type": "module",
+  "private": false,
+  "scripts": {
+    "start": "bun run src/index.ts"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/react": "^19.2.10",
+    "@types/react-dom": "^19.2.3"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.72.1",
+    "@modelcontextprotocol/sdk": "^1.17.5",
+    "@types/js-yaml": "^4.0.9",
+    "cac": "^6.7.14",
+    "ink": "^6.6.0",
+    "ink-text-input": "^6.0.0",
+    "jotai": "^2.17.0",
+    "js-yaml": "^4.1.1",
+    "react": "^19.2.4",
+    "zod": "^3.25.0",
+    "zustand": "^5.0.11"
+  }
+}

package/src/cli/index.tsx

@@ -0,0 +1,4 @@
+import { App } from "../render/index";
+import { render } from "ink";
+
+render(<App />);