deconwork 0.0.1__tar.gz

deconwork-0.0.1/PKG-INFO

@@ -0,0 +1,210 @@
+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 复用同一套实现。

deconwork-0.0.1/README.md

@@ -0,0 +1,200 @@
+# 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 复用同一套实现。

deconwork-0.0.1/deconwork/__init__.py

@@ -0,0 +1,13 @@
+"""DeconWork 独立程序包入口。"""
+
+from __future__ import annotations
+
+
+def main(argv=None):
+    """延迟导入 CLI 入口，避免 `python -m deconwork.runtime` 的重复导入警告。"""
+    from .runtime import main as runtime_main
+
+    return runtime_main(argv)
+
+
+__all__ = ["main"]