deconwork 0.0.2

DeconWork standalone desktop agent runtime powered by klynx.

DeconWork 使用教程（中文版）

DeconWork 是独立程序，klynx 仅作为底层依赖库使用。

运行形态分为两个独立进程：

1. 主进程：终端对话（ReAct）。
2. 心跳进程：定时读取 heartbeat.md 并触发自动化任务。

1. 安装

发布安装：

pip install -U deconwork

安装后可直接执行：

DeconWork

首次执行任意 DeconWork 命令时，会自动初始化安装目录下的 deconwork.env 与 deconwork_runtime/。

2. 快速开始

1. 初始化配置与运行时文件：

DeconWork config init

2. 选择模型并配置 API Key：

DeconWork config model

3. 启动主进程（对话）：

DeconWork
# 或 DeconWork run

如果当前未完成模型配置（例如缺少 API key），会自动进入 DeconWork config model 向导。

4. （可选）在另一个终端启动心跳进程：

DeconWork heartbeat

3. 主进程对话命令

启动 DeconWork 后支持以下命令：

1. /new：新建会话（生成新会话 ID）。
2. /sessions：查看最近保存的会话 ID。
3. /resume <session_id>：恢复历史会话。
4. /status：查看当前状态（含权限模式/命令执行开关）。
5. /clear：等价于 /new。
6. /quit：退出主进程。

说明：每轮对话后会自动将会话按 ID 持久化。

4. 心跳进程命令

持续运行心跳：

DeconWork heartbeat

只触发一次心跳后退出：

DeconWork heartbeat --once

5. 配置命令

DeconWork config show
DeconWork config init
DeconWork config set <KEY> <VALUE>
DeconWork config model --list
DeconWork config model
DeconWork config model --select kimi-k2.5
DeconWork config env path
DeconWork config env show
DeconWork config env show --raw
DeconWork config env set <KEY> <VALUE>
DeconWork config env unset <KEY>

配置工作目录（可选，不配置则默认安装目录）：

DeconWork config set DECONWORK_WORKING_DIR <你的项目目录>

6. 权限与沙箱配置

DeconWork 支持两种权限模式：

1. workspace：工作目录沙箱。
2. global：全局权限（默认，可访问工作目录外路径）。

当前权限实现方式：属于 Agent 工具层约束。workspace 模式通过工具路径校验（virtual_root）限制文件操作范围，并通过 allow-shell 控制命令执行开关。 注意：这不是 OS 级强隔离沙箱；如果需要系统级隔离，请自行配置容器或操作系统沙箱（如 Windows Sandbox / 容器 / 虚拟机）。

查看当前权限配置：

DeconWork config permission

切换权限模式：

DeconWork config permission --mode workspace
DeconWork config permission --mode global

用沙箱语义切换（等价模式切换）：

DeconWork config permission --sandbox on   # 等价 workspace
DeconWork config permission --sandbox off  # 等价 global

控制是否允许 execute_command：

DeconWork config permission --allow-shell true
DeconWork config permission --allow-shell false

分别控制关键文件是否允许写入（默认都为 true）：

DeconWork config permission --write-rules false
DeconWork config permission --write-memory false
DeconWork config permission --write-heartbeat false

7. 常用环境变量

1. DECONWORK_MODEL_PROVIDER
2. DECONWORK_MODEL_NAME
3. DECONWORK_API_BASE
4. DECONWORK_HEARTBEAT_ENABLED
5. DECONWORK_HEARTBEAT_INTERVAL
6. DECONWORK_HEARTBEAT_LOCK_POLICY（skip_if_busy / wait）
7. DECONWORK_WORKING_DIR（Agent 工作目录，默认安装目录）
8. DECONWORK_MAX_ITERATIONS（单轮最大循环次数，默认 200）
9. DECONWORK_APPEND_MAX_TOKENS
10. DECONWORK_PERMISSION_MODE（workspace / global，默认 global）
11. DECONWORK_ALLOW_SHELL_COMMANDS（true / false）
12. DECONWORK_ALLOW_WRITE_RULES_FILE（true / false）
13. DECONWORK_ALLOW_WRITE_MEMORY_FILE（true / false）
14. DECONWORK_ALLOW_WRITE_HEARTBEAT_FILE（true / false）

8. 安装目录中的文件布局

DeconWork 会把配置和运行时文件固定到安装目录下：

<install_dir>/
  deconwork.env
  deconwork_runtime/
    rules.md
    memory.md
    heartbeat.md
    conversations/
      index.json
      <session_id>.json

其中 rules.md、memory.md、heartbeat.md 会作为运行时附加上下文输入。

说明：以上是配置与运行时文件位置；Agent 实际执行的工作目录由 DECONWORK_WORKING_DIR 决定。

9. 本地源码运行

在仓库源码中运行时，可直接使用模块入口：

cd DeconBear/DeconWork
python -m deconwork.runtime

该入口与安装后的 DeconWork CLI 复用同一套实现。