内容
# Factile
[](https://github.com/factile/factile/actions/workflows/verify.yml)
[](https://github.com/factile/factile/actions/workflows/release.yml)
[](https://pkg.go.dev/github.com/factile/factile)
[](LICENSE)
Factile 将您拥有的文档转换为结构化的、可信的上下文代理。
Factile 是一个本地优先的命令行工具，用于 Open Knowledge Format 软件包。它安装本地的 Markdown 知识，给它稳定的虚拟路径，并通过本地的 Go CLI 和本地 stdio MCP 服务器提供相同的读取器接口。
状态：早期本地优先的 v0.1.0 版本。JSON 输出旨在作为稳定的代理/脚本接口；CLI 文本和命令人体工程学可能在 v1.0 之前继续演变。
Factile 在此仓库中不实现远程软件包、托管 MCP、订阅、计费、身份验证、市场搜索或云同步。
## 安装
Factile 是一个名为 `factile` 的 Go 二进制文件。
从源代码构建或安装：
```bash
go install github.com/factile/factile/cmd/factile@latest
```
发布版本作为 GitHub Release 存档发布，包含 Linux、macOS 和 Windows 的 `checksums.txt`。下载适合您平台的存档，解压它，并将 `factile` 放在您的 `PATH` 中。
安装脚本支持 Linux 和 macOS。固定您要发布的标签：
```bash
curl -fsSL https://raw.githubusercontent.com/factile/factile/v0.1.0/install.sh | bash
```
从检出直接构建：
```bash
go build -o factile ./cmd/factile
./factile version
```
## 快速入门
在仓库中初始化 Factile：
```bash
factile init
factile list /
factile list / --brief
factile stat /project
factile context /project "项目概述"
```
默认情况下，`factile init` 在 `./.factile/knowledge/` 处创建一个本地知识软件包，在 `./.factile/` 下对其进行编目，并在 `/project` 处安装它。如果未提供 `--agent`，则 Factile 为仓库中检测到的支持的代理安装指导。
使用自定义知识位置或显式代理：
```bash
factile init --knowledge-base ./knowledge --agent codex
```
在不更改您的仓库的情况下，尝试捆绑的固定装置：
```bash
factile --mount-file ./testdata/mounts.toml list /
factile --mount-file ./testdata/mounts.toml list /product-docs
factile --mount-file ./testdata/mounts.toml read /product-docs/workflows/invoice-import
factile --mount-file ./testdata/mounts.toml search /product-docs invoice
factile --mount-file ./testdata/mounts.toml context /product-docs "发票导入工作流程"
factile --mount-file ./testdata/mounts.toml graph /product-docs/workflows/invoice-import
factile --mount-file ./testdata/mounts.toml validate /product-docs
```
## 路径
读取器命令使用 Factile 路径而不是文件系统路径。读取器可以浏览 `/`、`/project`、`/engineering` 和更深的文件夹，而无需知道每个路径是编目、软件包链接、文件夹还是概念。
常见的读取器命令：
```bash
factile list /
factile list / --brief
factile stat /project
factile read /project/overview
factile search /project "部署检查清单"
factile context /project "编辑前我应该知道什么？"
factile graph /project
factile validate /project
```
在知识库定义了命名视图时，将 `--view <id>` 与 `list`、`search`、`context` 和 `graph` 一起使用。视图缩小了为该命令读取的软件包，而不更改规范文档路径。
## JSON
每个返回数据的命令都支持稳定的 JSON：
```bash
factile --mount-file ./testdata/mounts.toml read /product-docs/workflows/invoice-import --json
```
`--format json` 仍然被接受为现有脚本的兼容别名。文本输出是为人类的。
## MCP
运行本地 stdio MCP 服务器：
```bash
factile --mount-file ./testdata/mounts.toml mcp serve --stdio
factile --mount-file ./testdata/mounts.toml mcp serve --stdio --read-only
```
MCP 适配器使用与 CLI 相同的 API 和 JSON 模型。读取器模式公开了 `factile_list`、`factile_stat`、`factile_read`、`factile_search`、`factile_context`、`factile_graph`、`factile_validate` 和只读知识库检查工具。具有写入能力的模式添加了编目和文档突变工具；使用 `--read-only` 进行默认代理读取。
## 管理知识
编目命令管理本地知识库：
```bash
factile kb list
factile kb inspect /project
factile kb create /engineering --title "工程"
factile kb link /engineering ./testdata/bundles/product-docs /engineering/docs --title "文档" --read-only
factile kb view set /engineering reader --bundle /engineering/docs
factile kb view delete /engineering reader
factile kb unlink /engineering/docs
```
文档写入命令需要对现有概念的显式修订：
```bash
factile create /project/runbooks/example --type Runbook --title "示例" --body ./body.md
factile write /project/runbooks/example --rev <rev> --body ./body.md
factile patch /project/runbooks/example --rev <rev> --set title="更新的标题"
factile rename /project/runbooks/example /project/runbooks/new-example --rev <rev>
factile delete /project/runbooks/new-example --rev <rev>
```
## 代理指导
在仓库中安装本地 Codex 发现指导：
```bash
factile skill install codex --scope repo
factile skill install codex --scope repo --mode curator --profile software
factile skill doctor codex --json
```
仓库范围的安装在该仓库中创建本地代理指导和 MCP 配置。读取器模式是默认模式，并使用 `--read-only` 配置 MCP。管理者模式安装编目/写入指导和具有写入能力的 MCP 命令。
第一个配置文件位于 `profiles/software/` 下作为数据：配置文件清单、Markdown 模板和 JSON 配方。配方是 v0.1.0 中的指导数据，而不是可执行的流程。
## 本地跟踪
设置 `FACTILE_TRACE_FILE` 以追加 CLI 和 MCP 调用本地 JSONL 使用记录：
```bash
FACTILE_TRACE_FILE=.factile/usage.jsonl factile context / "发票导入" --json
```
跟踪日志仅限本地，并且除非设置环境变量，否则处于禁用状态。
## 已知限制
Factile v0.1.0 故意仅限本地：
- 没有托管服务、远程软件包同步、身份验证、市场、计费或云 MCP 在此仓库中。
- 配方是种子指导数据，而不是可执行的流程。
- 文本输出是人类界面；为脚本和代理使用 JSON。
- 重命名报告反向链接警告；它不会自动重写链接。
- 更广泛的文档软件包尚未在此仓库中发布；README 涵盖了支持的 v0.1.0 接口。
## 支持的平台
发布存档目标：
- Linux amd64 和 arm64
- macOS amd64 和 arm64
- Windows amd64
源代码构建需要 Go 1.26 或更新版本。
## 验证
运行仓库检查：
```bash
./scripts/verify.sh
```
验证脚本运行格式化检查、测试、vet、跨平台构建和针对固定软件包的 CLI 烟雾测试。
当本地安装 GoReleaser 时，使用以下命令验证发布配置：
```bash
goreleaser check
```
如果未安装 `goreleaser`，则 `./scripts/verify.sh` 仍然涵盖了正常的仓库验证。
## 项目管理
源代码和普通的项目文档根据 [Apache License, Version 2.0](LICENSE) 许可。Factile 名称、徽标、品牌资产、产品身份和相关商标保留；参见 [NOTICE](NOTICE) 和 [TRADEMARKS.md](TRADEMARKS.md)。
有关贡献和项目行为，请参见 [CONTRIBUTING.md](CONTRIBUTING.md)、[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) 和 [SECURITY.md](SECURITY.md)。
