# Helm

**Repository Path**: stdin2/helm

## Basic Information

- **Project Name**: Helm
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-16
- **Last Updated**: 2026-10-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Helm

Helm 是面向个人长期使用的 Personal Agent Harness。

当前完成工程基线和 Phase 01 / Task 01 的 Personal Knowledge Core：递归扫描 Markdown、增量同步 SQLite FTS5 索引、搜索和读取当前原文。运行时仅使用 Python 标准库，无需 API Key。当前不接入 Agent Runtime。

## 开发

需要 Python 3.11+、内置 SQLite FTS5 和 [uv](https://docs.astral.sh/uv/getting-started/installation/)。在仓库根目录执行：

```bash
uv sync --locked
uv run python -m helm
uv run pytest
uv run ruff check .
uv build
```

无参数运行入口输出 `Helm OK` 后退出，不创建运行文件。

## Personal Knowledge

原文默认位于 `workspace/knowledge/`，索引默认位于 `var/knowledge.db`，均已忽略 Git。先自行创建知识目录并放入 UTF-8 Markdown；不存在或不可读的目录会使同步失败，避免误清理索引。递归处理 `.md`（扩展名不区分大小写），不支持其他文件格式。

```bash
uv run python -m helm knowledge sync
uv run python -m helm knowledge search "智能合约"
uv run python -m helm knowledge read research.md 1 3
```

`sync` 输出 JSON 计数 `added / modified / deleted / unchanged`。`search` 输出 JSON 结果，包含相对路径、标题层级、1-based 闭区间行号、chunk 原文和排名分值。`read` 独立读取当前文件的指定行，输出 UTF-8 原文；不从索引取回缓存。

通过 `HELM_KNOWLEDGE_DIR`、`HELM_KNOWLEDGE_DB` 环境变量覆盖路径，或在子命令前显式指定：

```bash
uv run python -m helm knowledge --root path/to/knowledge --db path/to/knowledge.db sync
uv run python -m helm knowledge --root path/to/knowledge --db path/to/knowledge.db search "智能合约" --limit 5
```

路径相对于当前工作目录；`.env.example` 仅作变量说明，程序不自动读取 `.env`。自定义位置也应保持在 Git 忽略范围内。数据库绑定解析后的知识根目录，不能直接用于另一个根目录。

每次同步计算文件字节的 SHA-256；未变化的文件保留现有索引和时间戳，新增、修改和删除在同一个 SQLite transaction 中更新。扫描或写入失败保留此前索引。没有文件 watcher，资料修改后需主动再次 `sync`；搜索结果行号可能已过期，重要内容须读取当前原文核对。

Chunk 按 ATX 标题（`#` 至 `######`）划分，保留父标题层级和精确 LF/CRLF 行映射；围栏代码中的标题不触发划分。长 section 保持整块，不做语义拆分；不解析完整 Markdown（例如 Setext 标题）。

启动时实际探测 FTS5 tokenizer，优先采用 `trigram`，至少三个连续非空白字符的查询作为转义后的字面短语交给 FTS5，以 BM25 升序排名。短查询采用不区分大小写的字面 substring 扫描；没有 trigram 时采用 FTS5 `unicode61` 建索引，并用相同的简单 substring fallback 支持中文查询。Fallback 按路径和起始行排序，`score` 为 `null`，大知识库下会比 FTS5 慢。查询不接受 FTS 运算符语法。

读取 API 拒绝绝对路径、`..`、Windows drive / UNC / alternate data stream 和指向根目录外的链接。扫描拒绝链接目录和 Windows reparse 目录。此路径检查用于本地受信任文件树，不是对并发恶意替换文件的完整 sandbox。

索引是派生数据，可关闭运行命令后删除数据库，再执行 `sync` 从原文完整重建；不要删除 Markdown 原文。

应用接口无需调用者写 SQL：

```python
from helm.knowledge import KnowledgeBase

knowledge = KnowledgeBase(root="workspace/knowledge", database="var/knowledge.db")
summary = knowledge.sync()  # SyncResult
results = knowledge.search_knowledge("智能合约", limit=5)  # list[SearchResult]
if results:
    hit = results[0]
    original = knowledge.read_knowledge_source(
        hit.source_path, hit.start_line, hit.end_line
    )
```

## 文档

- [产品需求](docs/product.md)
- [系统架构](docs/architecture.md)
- [开发阶段](docs/phases.md)
- [架构决策](docs/decisions/README.md)
- [当前 Task Packet](docs/tasks/phase-01-task-01.md)
- [开发约束](AGENTS.md)