Metadata-Version: 2.4
Name: deconwork
Version: 0.0.1
Summary: DeconWork standalone desktop agent runtime powered by klynx.
Author: QZX
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: klynx>=0.0.17
Requires-Dist: python-dotenv>=1.0.0

﻿# DeconWork 使用教程（中文版）

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

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

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

## 1. 安装

发布安装：

```bash
pip install -U deconwork
```

本地可编辑安装（开发模式）：

```bash
pip install -e DeconBear/DeconWork
```

安装后可直接执行：

```bash
DeconWork
```

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

## 2. 快速开始

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

```bash
DeconWork config init
```

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

```bash
DeconWork config model
```

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

```bash
DeconWork
# 或 DeconWork run
```

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

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

```bash
DeconWork heartbeat
```

## 3. 主进程对话命令

启动 `DeconWork` 后支持以下命令：

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

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

## 4. 心跳进程命令

持续运行心跳：

```bash
DeconWork heartbeat
```

只触发一次心跳后退出：

```bash
DeconWork heartbeat --once
```

## 5. 配置命令

```bash
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>
```

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

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

## 6. 权限与沙箱配置

DeconWork 支持两种权限模式：

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

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

查看当前权限配置：

```bash
DeconWork config permission
```

切换权限模式：

```bash
DeconWork config permission --mode workspace
DeconWork config permission --mode global
```

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

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

控制是否允许 `execute_command`：

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

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

```bash
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 会把配置和运行时文件固定到安装目录下：

```text
<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. 本地源码运行

仓库内也可直接运行包装入口：

```bash
python DeconBear/DeconWork/DeconWork_agent.py
```

它与 `DeconWork` CLI 复用同一套实现。
