一个会主动找你的 AI 伙伴——不只是被动回答问题，还能根据你订阅的信息源主动判断"现在该不该发消息、发什么"，在空闲时自主执行后台任务。
如果你想让自己的 Akashic 具备和作者差不多的扩展能力，先看社区插件组织：
很多能力现在都不是写死在主仓里，而是做成独立插件仓库，例如：
steam-mcpfeed-mcphuayue-skills
如果 Akashic 已经在运行，你通常可以直接像聊天一样让它安装：
帮我安装这个插件试试看：
https://github.com/akashic-plugins/steam-mcp
或者更自然一点：
steam mcp 我想用插件方式加载，你帮我把这个插件装一下看看能不能用：
https://github.com/akashic-plugins/steam-mcp
Akashic 理想上的动作应该是：
┌─ 安装插件
│ ├─ 识别 GitHub 插件仓库
│ ├─ 执行 plugin-install
│ ├─ 检查 manifest.toml 与 plugin.py
│ └─ Runtime 自动发现并原子发布新快照
└─ 不重启，下一次执行使用新代际
安装、升级、启停、源码和 config.local.toml 修改都会自动热重载。正在执行的请求保持旧代际，新请求统一使用新代际；候选验证失败时继续保留旧版本。
想看完整机制，直接看 插件系统 Handbook。
需要 Python 3.12。
git clone <this-repo>
cd akashic-agent
uv venv && uv pip install -r requirements.txt -e sdk/python没有 uv？先 pip install uv。
1. 首次配置并启动 Akashic Web
正式 profile 安装完成后，先运行一次通用 setup 向导；它会让已安装插件执行各自声明的
setup。Prompt 包的 setup 只创建缺失的 memory/VEDA.md，不会覆盖已有人格。未完成这一步
就直接启动时，Prompt 会对缺失人格明确失败：
uv run python main.py setup --config /path/to/config.toml --workspace /path/to/workspace发行容器同样使用入口的 setup 命令完成首次配置：
docker run --rm --env-file /path/to/runtime.env \
-v /srv/data/services/akashic/state:/srv/data/services/akashic/state \
<akashic-image> setup配置已存在时，向导默认保留它并继续运行已安装插件 setup；只有确认覆盖才会生成新的 Core 配置。 setup 失败会保持失败可见，不应直接启动首个 Prompt。
uv run python main.pySupervisor 会始终提供唯一的本机 Web 入口：http://127.0.0.1:2236。访问后直接进入 Chat；没有模型配置时，Chat 会保留完整界面并引导进入“模型与认证”。
第一次运行不需要先创建 config.toml。打开设置中心，选择一种认证方式：
| 认证方式 | 适用场景 |
|---|---|
| API Key | 任意 OpenAI Chat Completions 兼容端点 |
| OpenCode Go | 粘贴 OpenCode Go Key，或复用本机已有的 OpenCode Go 登录 |
| Codex Auth | 复用本机 Codex 登录，未登录时按页面提示完成设备授权 |
打开 2236 Chat
│
├── 点击“连接模型”
├── 选择 Provider 与认证
├── 读取或填写模型
├── 发送最小真实请求验证
└── 保存配置 → 同一页面自动恢复对话
模型连接和凭据由内置 models 普通插件写入
<workspace>/model-registry.sqlite3，文件权限为 0600；设置 API 和页面不会回显
已经保存的密钥。切换连接时，旧模型仍会保留，切回来无需重新输入密钥。
OpenCode Go 会动态读取订阅当前提供的模型，隐藏已知走 Messages API 的型号，其余型号 默认按 Chat Completions 验证。因此新增 Chat Completions 型号通常不需要更新 Akashic。
2. 仅初始化 Core（不创建业务人格）
仍然可以使用原有命令：
uv run python main.py setup # 交互向导
uv run python main.py init # 非交互，CI/自动化用init 只创建 Core 和 workspace 配置；它不创建 VEDA。模型仍在 2236 的“模型”页添加。
根 config.toml 只接受 Core 中立设置，最小示例：
[runtime]
workspace = "~/.akashic/workspace"
[app_server]
enabled = true
listen = ""
max_connections = 32
ingress_queue_size = 128
outbound_queue_size = 512安装 akashic_clients 正式插件后，在其安装身份对应的 workspace data root
（默认为 <workspace>/plugin-data/akashic_clients-release/config.local.toml）配置 Web/Mobile：
enabled = true
[web]
enabled = true
[mobile_realtime]
enabled = falseTelegram、QQ 和其他业务配置同样由各自已安装插件的 config.local.toml 拥有；Core 不读取
[channels.*]、[mobile_realtime] 或模型业务表。若安装市场身份不是 release，以安装清单给出的
plugin-data/<name>-<marketplace>/ 为准。
当前状态作为新的迁移基线，历史兼容脚本已经退役；Yoyo 保留用于未来升级。
Core 只加载自有迁移和正式安装插件声明的 bundle，以 <workspace>/migrations.sqlite3
记录成功回执。旧账本与用户数据保留，不依赖 Git 历史，也不重新执行已退役步骤。
新增迁移前请阅读 Yoyo 迁移维护手册 与 当前基线决定。未来已发布脚本只追加不修改； 业务迁移由相应插件拥有。
workspace 默认是 ~/.akashic/workspace。临时切换隔离环境时传
--workspace PATH；它的优先级高于 AKASHIC_WORKSPACE 和 config.toml。
个人推荐：主模型使用 DeepSeek，轻量和视觉任务使用 Qwen。通信渠道推荐 Telegram；只想先本机试用时，打开 2236 绑定模型后即可直接对话。
3. 正式发行、运行与安全切换
正式发行使用 scripts/install-akashic.sh，它把精确 commit 的 Core 分发制品交给
akashic-release 完成构建和激活。未指定 commit 时固定本次执行开始时 main 的最新完整 SHA；需要
复现或回滚测试时显式指定 40 位 SHA：
curl -fsSL https://raw.githubusercontent.com/kachofugetsu09/akashic-agent/main/scripts/install-akashic.sh \
| sh -s -- --yes
curl -fsSL https://raw.githubusercontent.com/kachofugetsu09/akashic-agent/main/scripts/install-akashic.sh \
| sh -s -- --commit <full-40-character-sha> --yes安装器会显示 current/target identity 并等待确认；无人值守时加 --yes。只准备镜像、Bridge venv、
manifest、unit 和稳定 CLI 而不启动服务时加 --no-activate。首次激活前，
/srv/data/services/akashic/state/config.toml、workspace/ 和 plugin-home/ 必须已经由 operator
准备好；没有现成配置时从 config.example.toml 复制后按目标机编辑，不能把测试配置或假凭据带入正式
state。若配置没有 OpenCode Go 凭据，安装进程还必须从受保护的环境变量取得
OPENCODE_GO_API_KEY。安装器不会把软件更新授权解释成正式数据迁移授权。
这条路径的构建边界是：
exact commit
└─ 临时 clean checkout（只作为构建和 Host Bridge identity 输入）
├─ Core distribution builder → core.tar + 独立 *.bundle + profile/report
└─ Host Bridge / systemd / Compose → runtime-sources/<commit>
正式 Docker image 从 core.tar 解出 Core，并在构建时拒绝 plugins/ 业务源码；插件只能由 profile
声明的独立 bundle 通过正式 installer 安装。宿主上的 runtime-sources/<commit> 供 Host Bridge、Compose
模板和 identity 校验使用，不是 Core 的业务插件搜索路径。build_host_runtime_release.py --legacy-checkout
只保留给旧开发兼容，不能用于正式发行，也不能让镜像通过 checkout 自动装配插件。
安装后用稳定 CLI 核对实际身份或恢复上一代软件：
akashic-release doctor
akashic-release rollback --yesruntime.env 由激活事务原子生成，至少闭合 AKASHIC_RUNTIME_COMMIT、
AKASHIC_RUNTIME_TREE、AKASHIC_IMAGE、AKASHIC_RELEASE_MANIFEST 和
AKASHIC_RUNTIME_CHECKOUT。容器入口会用镜像内 runtime-info.json 对照 commit/tree；doctor 还会核对
release manifest、content-addressed image、Host Bridge checkout、toolchain 和 Bridge RPC。不要手改这些
generation 字段；需要更新时重新准备并激活一个完整 release。
首次正式启动时，distribution entrypoint 先用 default profile 校验并安装独立 bundle，随后在
<workspace>/runtime/distribution-install.json 写入安装 receipt。后续重启只校验历史 receipt、当前
manifest 和 stable artifact，不重新安装、启用默认 profile 或覆盖插件配置；因此 operator 后续禁用、卸载
或用不同名称的 provider 替换插件后，重启仍保持当前组合。卸载走正在运行的 Core 控制面，例如
python main.py plugin-uninstall <plugin-id> --config PATH --workspace PATH；普通卸载保留该插件的
plugin-data。要恢复软件代际使用 akashic-release rollback --yes，它恢复 runtime/env 和服务身份，
不回滚已经写入 Workspace 的业务数据或外部效果。
发布验收还必须单独证明 Core-only 启停。下面的命令把分发制品写到仓库外；runner 会先从 core.tar
启动并停止无业务源码的 Core，再执行 bundle 组合。检查报告中的 core_bootstrap.status 与 stop 证据；
这一步证明 Core tar 不依赖 checkout 或业务源码，不等于默认 profile 的全量业务验收。
release_dir="$(mktemp -d /var/tmp/akashic-distribution.XXXXXX)"
release_sha="<full-40-character-sha>"
python scripts/build_plugin_distribution.py \
--repository "$PWD" --revision "$release_sha" --output "$release_dir"
python docker/debug/plugin_external_acceptance.py \
--distribution "$release_dir/distribution.json" \
--core-tar "$release_dir/core.tar" \
--repo-root "$PWD" \
--output "$release_dir/acceptance.json"完整边界见 Core 与 Host Bridge 安装设计。
无参数启动会先进入内置 supervisor，再由它启动正式 gateway。这样核心代码或主配置
确需完整重载时，Agent 可以通过当轮 tool_search 解锁 agent_restart，并在回复持久化、
送达和私有提交证据全部完成后安全拉起下一代进程。需要让调试器直接附着未托管 gateway
时，显式运行 uv run python main.py gateway；该模式不会注册自重启工具。
在 2236 的“模型与认证”切换 Provider、模型或默认角色时，Gateway 会原子发布新模型代际，不停止接收新 turn，也不重启进程。已经开始的执行继续使用旧代，下一个真正开始的执行使用新代；候选 配置或真实请求校验失败时保持原配置和当前代际。
从终端或 supervisor 切换到 PyCharm 前，先优雅停止当前 workspace 的 runtime：
./scripts/stop-runtime.sh脚本遵循 --workspace、AKASHIC_WORKSPACE、config.toml 的 workspace
优先级，优先停止 supervisor，并等待 runtime 真正释放实例锁。它不会删除锁文件，
也不会在超时后自动强制终止进程。PyCharm 仍直接运行 main.py，默认同样进入
supervisor；需要直接调试 child 时把程序参数设为 gateway。也可以把
scripts/stop-runtime.sh 配置为 Run Configuration 的 Before Launch external tool。
如果配置了 Telegram / QQ，也可以直接给 bot 发一条消息开始对话。
Akashic Mobile 是一个通过独立实时网关连接 Akashic Agent 的 Android 客户端。远程接入推荐使用 Cloudflare Tunnel：Web Chat 和模型设置继续留在本机 127.0.0.1:2236，Tunnel 只转发由 Akashic 设备认证保护的 6323 端口。
1. 在 `<workspace>/plugin-data/akashic_clients-<marketplace>/config.local.toml`
启用 `[mobile_realtime]`（默认正式安装身份是 `release`）
2. 用 Cloudflare Tunnel 把一个公共域名转到 https://127.0.0.1:6323
3. 在本机 Web Chat 点击“连接手机”，用 Akashic Mobile 扫描二维码
4. 两端核对六位确认码，在电脑上批准设备
- Android 安装包：https://github.com/kachofugetsu09/akashic-mobile/releases/latest
- 配置、Cloudflare、验证与排障：移动端接入手册
首次配对成功后，手机会保存设备密钥，正常升级应用或重连无需再次扫码。
Android 的对话界面与 Web Chat 共用 frontend/chat/src。只修改 React、CSS 或插件插槽时，
不需要重新打包 APK；服务端把构建结果发布成不可变 WebUI generation，支持 OTA 的客户端会
下载、校验并切换到所选频道。只有原生壳、Native Bridge 协议或最低原生 build 发生变化时
才需要发布新的 APK。
先从发布仓读取当前服务身份，并为指针和可达资源创建恢复点：
AKASHIC_WEBUI_SERVER_ID="$(sqlite3 -readonly \
~/.akashic/workspace/mobile-webui/publication.sqlite3 \
"SELECT value FROM webui_meta WHERE key = 'server_id'")"
AKASHIC_PLUGIN_HOME="${AKASHIC_PLUGIN_HOME:-$HOME/.akashic-plugin}"
AKASHIC_CLIENT_ARTIFACT="$AKASHIC_PLUGIN_HOME/cache/release/akashic_clients/.artifacts/<installed-revision>"
test -f "$AKASHIC_CLIENT_ARTIFACT/mobile_webui/release_cli.py"
.venv/bin/python "$AKASHIC_CLIENT_ARTIFACT/mobile_webui/release_cli.py" backup \
--workspace ~/.akashic/workspace \
--server-id "$AKASHIC_WEBUI_SERVER_ID" \
--destination ~/.akashic/backups/mobile-webui-"$(date +%Y%m%d-%H%M%S)"开发中的 dirty 前端只能发布到 Preview，适合在配置为 Preview 频道的真机上验收：
.venv/bin/python "$AKASHIC_CLIENT_ARTIFACT/mobile_webui/release_cli.py" publish \
--source-repository "$PWD" \
--workspace ~/.akashic/workspace \
--server-id "$AKASHIC_WEBUI_SERVER_ID" \
--allow-dirty \
--actor local-preview合并后切到最新且干净的 main，再从确定的 commit 发布 Stable；普通设备随后会通过 OTA
取得该 generation：
git checkout main
git pull --ff-only origin main
test -z "$(git status --porcelain)"
AKASHIC_WEBUI_SOURCE_COMMIT="$(git rev-parse HEAD)"
.venv/bin/python "$AKASHIC_CLIENT_ARTIFACT/mobile_webui/release_cli.py" publish \
--source-repository "$PWD" \
--workspace ~/.akashic/workspace \
--server-id "$AKASHIC_WEBUI_SERVER_ID" \
--source-commit "$AKASHIC_WEBUI_SOURCE_COMMIT" \
--stable \
--actor local-stable用 python "$AKASHIC_CLIENT_ARTIFACT/mobile_webui/release_cli.py" inspect 核对 Stable/Preview 的 generation、协议窗口和
minimum_native_build。发布只更新 WebUI 发布仓，不会改写会话、记忆或插件数据。
你的消息 → [被动回复] ──→ agent loop ──→ 回复
│
├── 记忆系统 ─── 每轮注入长期记忆 + 模型窗口水位 compaction
│
└── 插件系统 ─── 拦截命令、注入协议、阻断工具、挂载新工具...
[主动推送] ──→ 定期轮询 ──→ 三路数据 (alert/content/context) ──→ LLM 决策 ──→ 推送或跳过
│
└── [Drift] ──→ 没东西推时执行后台任务 (SKILL.md)
| 想看什么 | 文档 |
|---|---|
| 怎么首次配置或切换 Provider | 启动后访问 http://127.0.0.1:2236/#models，支持 API Key、OpenCode Go 和 Codex Auth |
| 怎么打开本机 Web Chat | 启动后访问 http://127.0.0.1:2236；没有模型时页面会直接引导配置 |
| 怎么用 Android 手机远程连接 | 移动端接入手册 |
| 怎么让 agent 主动推送消息、怎么配数据源 | _handbook/proactive-guide.md |
| 怎么写后台任务让 agent 空闲时自动干活 | _handbook/drift-guide.md |
| MEMORY.md / SELF.md / consolidation / 记忆怎么流转 | _handbook/memory-markdown.md |
| 怎么写插件介入生命周期、注册工具 | _handbook/plugins-tutorial.md |
收到消息 → 记忆检索 → 工具调用 → 流式回复。每轮经过 6 个 Phase（BeforeTurn → BeforeReasoning → PromptRender → Reasoner → AfterReasoning → AfterTurn）。
插件有 4 种介入方式：PhaseModule 链（7 个 Phase 方法 + slot 依赖声明）、EventBus 装饰器（9 种事件）、@on_tool_pre（工具拦截）、@tool（注册工具）。见 插件系统。
Agent 根据电量模型自适应调整轮询频率——你刚聊完时不烦你（8 分钟一次），半天没动静就加速到 1 分钟一次。每轮拉取三路 MCP 数据：
- alert — 高优先级告警，直接透传
- content — 内容流，逐条 LLM 评分分类
- context — 背景上下文，概率注入做 fallback
对话通过 session context compaction ledger 按模型真实 context window 压缩；Markdown consolidation 从 checkpoint 的 exact source plan 提取 PENDING 候选，并发布 ConsolidationCommitted 供语义记忆消费。Optimizer 定时将 PENDING 归档到 MEMORY.md；当前运行时不创建或写入 HISTORY.md。
见 记忆系统。
没内容可推时 agent 不空转——执行你写的 SKILL.md（分步操作指南），比如审计长期记忆是否准确、补用户画像、自我诊断。
见 Drift 指南。
uv run python main.py exec --new --final-only "总结最近上下文"
uv run python main.py app-server --stdio # 父进程托管 JSON-RPC app-server
uv run python main.py dashboard # 单独运行 Dashboard 调试入口
# 正式 Supervisor 只提供 http://127.0.0.1:2236，根页面是统一壳层并默认选中 Chat
uv run python main.py --help # 查看全部子命令
pytest tests/
akashic_RUN_SCENARIOS=1 pytest -c pytest-scenarios.ini tests_scenarios/所有运行时数据都在 [runtime].workspace 指定的目录下。默认值是
~/.akashic/workspace；可设置 AKASHIC_WORKSPACE，也可以为单条命令传入
--workspace /absolute/path。优先级为 --workspace、AKASHIC_WORKSPACE、
config.toml。不同测试环境使用不同目录，不共享会话、记忆、附件或插件数据。
开发 checkout 的插件代码缓存和启停清单默认仍位于 $HOME/.akashic-plugin；需要完整隔离插件安装状态时，
额外设置 AKASHIC_PLUGIN_HOME=/absolute/test/plugin-home。正式分发使用
/srv/data/services/akashic/state/plugin-home，只接受 release profile 或普通插件控制面发布的 artifact，
不会扫描仓库 checkout 的 plugins/。
从旧版升级时，第一次重启前显式复制旧插件数据；命令保留旧目录，目标已存在时拒绝覆盖：
uv run python scripts/migrate_plugin_data.py \
--workspace "$HOME/.akashic/workspace" \
--plugins-home "$HOME/.akashic-plugin"客户端连接 workspace 下的 akashic.sock，先以协议版本 2.0 完成 JSON-RPC
initialize/initialized，再使用 session/create、message/send、message/read
和 session/follow。发送 ACK 表示原始输入已经保存；回复随后追加。关闭连接只停止读取，
重连后按已处理的 seq 补读。旧 Thread/Turn 方法已由 Message v2 替代。
完整用法见 Python SDK 和 协议 schema。