101 lines
2.8 KiB
Markdown
101 lines
2.8 KiB
Markdown
# cli-anything-zhiyi — 参考实现
|
||
|
||
> 用 agent-cli-builder 方法论为织忆 (MemoryWeave) 构建的 Agent-native CLI
|
||
|
||
## 项目信息
|
||
|
||
| 项目 | 值 |
|
||
|------|-----|
|
||
| 源码 | `~/bin/cli-anything-zhiyi/` |
|
||
| 入口 | `cli-anything-zhiyi`（已 pip install -e） |
|
||
| API | `localhost:7821`（API key: `zhiyi-dev-key-2026`） |
|
||
| 技术栈 | Python 3.11, Click 8.4, prompt_toolkit（可选） |
|
||
| 测试 | 9 个测试全部通过 |
|
||
| SKILL.md | `cli_anything/zhiyi/skills/SKILL.md` |
|
||
|
||
## 命令设计
|
||
|
||
```
|
||
cli-anything-zhiyi
|
||
├── health → 5 组件系统诊断
|
||
├── search <query> → 记忆搜索（--top-k, --mode, --diversity）
|
||
├── stats → 统计（--type memories/graph/cache/metrics）
|
||
├── graph
|
||
│ ├── navigate → 图谱导航（--entity, --hops）
|
||
│ ├── cleanup → 图谱清理
|
||
├── feedback → 记忆反馈（--id, --useful/--not-useful）
|
||
├── repl → 交互模式（默认）
|
||
```
|
||
|
||
## 架构层次
|
||
|
||
```
|
||
zhiyi_cli.py ← Click CLI 入口 + 所有命令组
|
||
core/client.py ← ZhiYiClient: _get/_post 封装所有 API 端点
|
||
tests/test_core.py ← 9 个单元测试
|
||
skills/SKILL.md ← Agent 可发现的 skill 定义
|
||
```
|
||
|
||
## 关键代码模式
|
||
|
||
### 1. Client 封装（client.py）
|
||
```python
|
||
class ZhiYiClient:
|
||
def __init__(self, base=None, api_key=None):
|
||
self.base = (base or DEFAULT_BASE).rstrip("/")
|
||
self.api_key = api_key or DEFAULT_KEY
|
||
|
||
def _get(self, path) -> dict:
|
||
# urllib.request with X-API-Key header, timeout=10
|
||
def _post(self, path, data) -> dict:
|
||
# JSON body + Content-Type + X-API-Key, timeout=30
|
||
```
|
||
|
||
### 2. 双输出模式（zhiyi_cli.py）
|
||
```python
|
||
def output(data, message=""):
|
||
if _json_output:
|
||
click.echo(json.dumps(data, indent=2, ensure_ascii=False, default=str))
|
||
else:
|
||
# Human: icons + structured formatting
|
||
```
|
||
|
||
### 3. REPL 默认入口
|
||
```python
|
||
@click.group(invoke_without_command=True)
|
||
@click.pass_context
|
||
def cli(ctx, json_flag):
|
||
if ctx.invoked_subcommand is None:
|
||
ctx.invoke(repl)
|
||
```
|
||
|
||
## 验证命令
|
||
|
||
```bash
|
||
# 健康检查
|
||
cli-anything-zhiyi health
|
||
|
||
# 搜索（人类可读）
|
||
cli-anything-zhiyi search "织忆" --top-k 3
|
||
|
||
# 搜索（JSON 输出给 Agent）
|
||
cli-anything-zhiyi search "小唯" --json | jq .results[].content
|
||
|
||
# 统计
|
||
cli-anything-zhiyi stats
|
||
|
||
# 图谱导航
|
||
cli-anything-zhiyi graph navigate -e "织忆" -n 2
|
||
|
||
# 测试
|
||
python3 cli_anything/zhiyi/tests/test_core.py
|
||
```
|
||
|
||
## 对比：Hermes 插件 vs CLI 模式
|
||
|
||
| 维度 | Hermes 织忆插件 | cli-anything-zhiyi |
|
||
|------|----------------|-------------------|
|
||
| 使用场景 | 对话中自动 prefetch + 注入 | 终端直接查询 |
|
||
| 目标用户 | 小唯 A06 | 牧尘 / 其他 AI Agent |
|
||
| 输出 | 嵌入系统 prompt | 终端可读 / JSON |
|