工具、结果与 artifact

QitOS public API: tools

旧 host Read 使用从 0 开始的 offset 与正整数 limit：offset=2、limit=2 只选择第 3/4 行。空文件与 EOF 返回空 output；负数或非整数窗口失败，selection 元数据保留截断与后续行信息。Edit 默认要求唯一匹配，replace_all=True 才替换全部。 无匹配、非唯一匹配、权限拒绝与显式 expected_sha256 冲突均不修改文件。 这两个 alias 现在返回 canonical ToolResult，编号文本在 .output，状态与错误在对应字段， 不再把错误包装成成功字符串。原先直接使用字符串的调用方应先检查 .status 再读取 .output。 既有 validation/permission pipeline 继续决定权限。Host compatibility 仍在 Host 执行； Env read_file/edit_file 仍只使用 Env ops，保留从 1 开始的 line_offset。 不增加 Host 回退或隔离保证。

运行前注册工具。类工具契约是 execute(args, runtime_context)，run 仅兼容。检查 ToolResult 的 status、error_code、output、artifact_refs、outcome_unknown 和 worker_still_running，不能只看文本。并行需要真实的并发安全声明；完成顺序不等于声明顺序。publication 需显式授权并受平台和文件形状限制，cleanup 不发布。SandboxPublicationTool 虽位于 internal 模块，但在本教程作为显式注册的高级适配器使用，不是默认工具。

完整可运行教程 / Complete tutorial · API index

以下签名和字段由固定源码提取；签名是参考，不是可直接运行的程序。每个条目的源码链接绑定同一 runtime baseline。类型中的 Any 不代表任意对象均受支持，应结合上述行为契约和教程使用。

​

ToolRegistry

from qitos import ToolRegistry

Source @ 19f6258

用法与可执行示例

用法片段：接续上方完整教程中的对象，不是独立程序。

registry = ToolRegistry()
registry.register(summarize_note)

Registry for function tools, bound methods, tool objects, and ToolSets.

ToolRegistry(*, auto_short_aliases: bool=True) -> Any (see behavior contract)

Parameter	Type	Default
auto_short_aliases	bool	True

​

ToolRegistry.register

register(item: Any, name: Optional[str]=None, meta: Optional[ToolMeta]=None) -> 'ToolRegistry'

Parameter	Type	Default
item	Any	required
name	Optional[str]	None
meta	Optional[ToolMeta]	None

Source

​

function_tool

from qitos.core.function_tool_decorator import function_tool

Source @ 19f6258

用法与可执行示例

用法片段：接续上方完整教程中的对象，不是独立程序。

@function_tool(read_only=True, concurrency_safe=True)
def title(text: str) -> str:
    return text.split(":", 1)[0]

Decorator that creates a :class:`FunctionTool` from a plain function.

Can be used with or without parentheses::

    @function_tool
    def greet(name: str) -> str: ...

    @function_tool(name="custom", needs_approval=True)
    def greet(name: str) -> str: ...

Returns a :class:`FunctionTool` instance.

function_tool(func: Optional[Callable[..., Any]]=None, *, name: Optional[str]=None, description: Optional[str]=None, timeout_s: Optional[float]=None, max_retries: int=0, retry_policy: Optional[RetryPolicy]=None, on_failure: Optional[Callable]=None, read_only: bool=False, concurrency_safe: Optional[bool]=None, needs_approval: bool=False, **extra_meta: Any) -> Any

Parameter	Type	Default
func	Optional[Callable[..., Any]]	None
name	Optional[str]	None
description	Optional[str]	None
timeout_s	Optional[float]	None
max_retries	int	0
retry_policy	Optional[RetryPolicy]	None
on_failure	Optional[Callable]	None
read_only	bool	False
concurrency_safe	Optional[bool]	None
needs_approval	bool	False

​

BaseTool

from qitos.core.tool import BaseTool

Source @ 19f6258

用法与可执行示例

用法片段：接续上方完整教程中的对象，不是独立程序。

# Class tools implement execute, not the compatibility run method.
class EchoTool(BaseTool):
    name = "echo"
    description = "Return a trusted input"
    def execute(self, args, runtime_context=None):
        return ToolResult(output=args)

Base abstraction for callable tools.

BaseTool(spec: ToolSpec) -> Any (see behavior contract)

Parameter	Type	Default
spec	ToolSpec	required

​

BaseTool.execute

execute(args: Dict[str, Any], runtime_context: Optional[Dict[str, Any]]=None) -> Any

Parameter	Type	Default
args	Dict[str, Any]	required
runtime_context	Optional[Dict[str, Any]]	None

Execute tool with optional runtime context.

Source

​

ToolResult

from qitos.core.tool_result import ToolResult

Source @ 19f6258

用法与可执行示例

用法片段：接续上方完整教程中的对象，不是独立程序。

result = ToolResult(output={"title": "Session"})
print(result.status, result.output, result.outcome_unknown)

Lossless terminal outcome for one declared action/tool slot.

Field	Type	Default
status	ToolResultStatus	'success'
output	Any	None
error	str | None	None
metadata	Dict[str, Any]	field(default_factory=dict)
tool_name	str | None	None
action_id	str | None	None
model_output	Any	None
error_kind	ToolErrorKind | None	None
error_code	str | None	None
recoverable	bool	False
recovery_hint	str | None	None
next_action	Dict[str, Any] | None	None
complete	bool	True
truncated	bool	False
omitted	Dict[str, int]	field(default_factory=dict)
attempts	int	1
latency_ms	float	0.0
declared_effects	list[Dict[str, Any]]	field(default_factory=list)
filesystem_changes	list[Dict[str, Any]]	field(default_factory=list)
artifact_refs	tuple[ArtifactRef, ...]	()
normalized_request	Dict[str, Any]	field(default_factory=dict)
provenance	Dict[str, Any]	field(default_factory=dict)
worker_still_running	bool	False
attempt_id	AttemptIdentity | None	None
effect_ref	str | None	None
effect_state	EffectState	'no_effect_declared'
idempotency_ref	str | None	None
retry_disposition	RetryDisposition	'not_evaluated'
reconciliation_required	bool	False
outcome_unknown	bool	False
late_result	bool	False
owner_generation	int | None	None
stale_owner	bool	False
batch_closure	Dict[str, Any]	field(default_factory=dict)
schema_version	str	TOOL_RESULT_SCHEMA_VERSION

​

ArtifactRef

from qitos.core.artifact import ArtifactRef

Source @ 19f6258

用法与可执行示例

用法片段：接续上方完整教程中的对象，不是独立程序。

# ref is an ArtifactRef obtained from a tool result.
print(ref.sha256)
body = composition.agent.config["artifact_resolver"].resolve(ref).body

Portable content-addressed pointer; never an artifact body or host path.

Field	Type	Default
artifact_id	str	required
resolver_key	str	required
sha256	str	required
media_type	str	required
byte_length	int	required
encoding	str	'binary'
sensitivity	str	'internal'
provenance_digest	Optional[str]	None
model_summary	Optional[str]	None
required	bool	True
schema_version	str	ARTIFACT_REF_SCHEMA_VERSION

​

ArtifactRef.from_dict

from_dict(value: Any) -> 'ArtifactRef'

Parameter	Type	Default
value	Any	required

Source

​

ActionExecutionPolicy

from qitos.engine.action_executor import ActionExecutionPolicy

Source @ 19f6258

用法与可执行示例

用法片段：接续上方完整教程中的对象，不是独立程序。

policy = ActionExecutionPolicy(mode="parallel", max_concurrency=2)
engine = Engine(NotesAgent(), runtime=RuntimeComposition(), action_execution_policy=policy)

Executor policy for action batches.

Field	Type	Default
mode	str	'serial'
fail_fast	bool	False
max_concurrency	int	4
parallel_tool_names	FrozenSet[str] | None	None

​

SandboxPublicationTool

from qitos.kit.tool.internal.publication import SandboxPublicationTool

Source @ 19f6258

用法与可执行示例

用法片段：接续上方完整教程中的对象，不是独立程序。

# Only after sandbox execution, with explicit publication authority:
publication = SandboxPublicationTool(
    composition.env, paths=["report.txt"],
    expected_input_digest=composition.env.input_digest,
)
composition.tool_registry.register(publication)

Opt-in tool restricted to paths and input digest approved by its caller.

SandboxPublicationTool(env: Any, *, paths: Iterable[str], expected_input_digest: str) -> Any (see behavior contract)

Parameter	Type	Default
env	Any	required
paths	Iterable[str]	required
expected_input_digest	str	required

​

SandboxPublicationTool.execute

execute(args: Any, runtime_context: Any=None) -> ToolResult

Parameter	Type	Default
args	Any	required
runtime_context	Any	None

Source