@zythegit/agent-hub 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,160 @@
1
- # Temporary Holding Version
1
+ # AgentHub (`ahub`)
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ > 跨 AI 编码客户端(Antigravity / Qoder / Claude / Codex / Pi / Trae 等)的双层规范投影、经验学习与技能分发平台。
4
+
5
+ 系统级与项目级双层正交零双投;Always-On 单槽位消除重复上下文;物理隔离个人(`personal`)与公司(`company`)双域资产;支持免编译配置扩展任意新客户端及变体。
6
+
7
+ > 📘 **深入设计文档与复制即用示例**:
8
+ > - 架构需求与投影矩阵:[docs/06-SYSTEM-AND-PROJECT-SCOPE-PRD.md](./docs/06-SYSTEM-AND-PROJECT-SCOPE-PRD.md)
9
+ > - 双层 SoT 配置、产物对照与端到端命令流:[docs/07-BEST-PRACTICES-EXAMPLES.md](./docs/07-BEST-PRACTICES-EXAMPLES.md)
10
+
11
+ ---
12
+
13
+ ## 安装与运行
14
+
15
+ ### 方式 1:全局安装(推荐)
16
+
17
+ ```bash
18
+ npm install -g @zythegit/agent-hub
19
+
20
+ # 验证安装
21
+ ahub --version
22
+ # 或
23
+ agent-hub --version
24
+ ```
25
+
26
+ ### 方式 2:免安装直接执行(npx)
27
+
28
+ ```bash
29
+ npx @zythegit/agent-hub sync
30
+ ```
31
+
32
+ ### 方式 3:从源码本地构建
33
+
34
+ ```bash
35
+ git clone https://github.com/zyTheGit/AgentHub.git
36
+ cd AgentHub
37
+ npm install
38
+ npm run build
39
+ npm link
40
+ ```
41
+
42
+ ---
43
+
44
+ ## 常用命令速查
45
+
46
+ | 全称命令 | 说明 | 常用简写 / 别名 |
47
+ | :--- | :--- | :--- |
48
+ | `ahub sync` / `ahub sync --all` | **默认先同步系统级(Layer 0),再同步全部项目** | `ahub s` / `ahub sync -a` |
49
+ | `ahub sync --system` | 仅同步系统级配置(Rules / Skills / Agents / System MCP) | `ahub sync -g` / `--global-only` |
50
+ | `ahub sync --projects-only` | 仅批量同步所有项目,不触碰用户主目录 | - |
51
+ | `ahub sync <项目名>` | 仅同步指定单个项目(系统级漂移时末尾提示) | `ahub s <项目名>` |
52
+ | `ahub sync --prune-legacy --dry-run` | 升级迁移:预览并按特征清理历史托管残留(绝不误伤非托管资产) | - |
53
+ | `ahub doctor` | 全量健康体检(双层漂移、重复注入、24KB/Token 预算与域隔离审计) | `ahub d` |
54
+ | `ahub hub restore` | 新机还原本机映射(支持纯 `personal` 单库)并自动同步系统级 | - |
55
+ | `ahub hub detach company --dry-run` | 离职一键卸载公司域预览(含投影/状态清理、跨域复检与 AGY 提醒) | - |
56
+ | `ahub project list` | 列出当前已纳管的所有项目 | `ahub project ls` |
57
+ | `ahub project add <路径>` | 纳管新项目并自动侦测技术栈 | - |
58
+ | `ahub remove <项目名> --clean` | 解绑项目并按 Manifest 精确清理投影与状态指纹 | `ahub rm <项目名> -c` |
59
+ | `ahub hub remove <hub> --clean` | 按 Hub(`personal\|company\|all`)批量解绑并清理投影 | `ahub hub rm <hub> -c` |
60
+ | `ahub learn harvest` / `distill` / `review` | 增量脱敏采集会话 → 提纯待审卡片 → 交互或 `--auto` 审核晋升 | - |
61
+ | `ahub learn remove <card-id>` | 从 `.local/pending/` 删除指定待审经验卡 | `ahub learn rm <card-id>` |
62
+
63
+ > 📌 **命令设计原则**:遵循 CLI 行业惯例,文档与帮助优先展示语义明确的全称命令,辅以标准动词/参数缩写(如 `sync` → `s`、`doctor` → `d`、`list` → `ls`、`remove` → `rm`)。
64
+
65
+ ---
66
+
67
+ ## 核心工作流
68
+
69
+ ### 1. 初始化与换机还原(支持纯个人单库)
70
+ ```bash
71
+ # 首次使用:初始化双 Hub 骨架与本机映射
72
+ ahub hub init
73
+
74
+ # 换新电脑:克隆 SoT 仓后一键还原(仅克隆 personal 仓亦可成功),
75
+ # 自动串联 ahub sync --system 并汇总缺失的 ${ENV_VAR} 环境变量清单
76
+ ahub hub restore
77
+ ```
78
+
79
+ ### 2. 旧仓迁移与日常双层同步
80
+ ```bash
81
+ # 从旧版升级时:先预览历史重复规则/错放 MCP 清理依据,确认后执行
82
+ ahub sync --prune-legacy --dry-run
83
+ ahub sync --prune-legacy
84
+
85
+ # 纳管新项目并触发同步
86
+ ahub project add /path/to/project
87
+ ahub sync <项目名>
88
+
89
+ # 日常最高频:系统级 + 全部项目一次同步到位
90
+ ahub sync
91
+
92
+ # 仅更新全局习惯 / 通用 Skill / 系统级 MCP
93
+ ahub sync --system
94
+ ```
95
+
96
+ ### 3. 会话经验学习闭环
97
+ ```bash
98
+ # 1. 多端增量采集并强制脱敏(Token / 密码 / 凭据)
99
+ ahub learn harvest --since 7d
100
+
101
+ # 2. 提纯为待审经验卡(存入 .local/pending/)
102
+ ahub learn distill
103
+
104
+ # 3. 审核晋升(支持终端交互确认,或 --auto 按置信度批量处理)
105
+ ahub learn review --auto
106
+
107
+ # 4. 双层同步至各端生效,并运行健康体检
108
+ ahub sync && ahub doctor --all
109
+ ```
110
+
111
+ ### 4. 解绑项目与离职一键卸载公司域
112
+ ```bash
113
+ # 解绑单个项目并按 Manifest 精确清理(托管块外手写内容与非托管技能 100% 完好保留)
114
+ ahub remove <项目名> --clean
115
+
116
+ # 离职一键卸载公司域:先预览影响面,确认后清理公司项目投影/状态/经验卡并完成跨域复检
117
+ ahub hub detach company --dry-run
118
+ ahub hub detach company
119
+
120
+ # 校验剩余个人项目健康
121
+ ahub doctor --all && ahub sync
122
+ ```
123
+
124
+ ---
125
+
126
+ ## 免代码扩展客户端与变体
127
+
128
+ 在配置根目录的 `custom-targets.yaml` 中,可通过 `extends` + `home_root` 一行适配内置客户端变体,或通过 `system` / `project` 声明全新工具(向下兼容 v1 扁平字段):
129
+
130
+ ```yaml
131
+ targets:
132
+ # 一行继承内置 qoder 并重定向主目录(适配 Qoder CN 版)
133
+ qoder-cn:
134
+ description: "Qoder CN IDE / CLI"
135
+ extends: qoder
136
+ home_root: "~/.qoder-cn"
137
+
138
+ # 声明全新客户端(示例:Cursor)
139
+ cursor:
140
+ description: "Cursor IDE"
141
+ project:
142
+ rules:
143
+ single_file: ".cursorrules"
144
+ dir: ".cursor/rules"
145
+ ext: ".mdc"
146
+ mcp:
147
+ path: ".cursor/mcp.json"
148
+ local_path: ".cursor/mcp.local.json"
149
+ skills_dir: ".cursor/skills"
150
+ ```
151
+
152
+ 保存后执行 `ahub sync` 即可生效。更多完整示例见 [docs/07-BEST-PRACTICES-EXAMPLES.md](./docs/07-BEST-PRACTICES-EXAMPLES.md)。
153
+
154
+ ---
155
+
156
+ ## 跨平台说明
157
+
158
+ - **Windows**:Skills 通过 Directory Junction(`mklink /J`)软链分发,改一处处处实时生效,免管理员权限。
159
+ - **macOS / Linux**:自动采用原生 Symbolic Link(`ln -s`)。
160
+ - **受限环境**:自动降级为带 `.agenthub-skill-manifest.json` 校验清单的实体拷贝。
package/dist/.gitkeep ADDED
File without changes