docs(comments): 注释中文化 · internal/runtime/orchestration(29 文件,纯替换)
CI / Backend (build / vet / test / cross-compile) (push) Has been cancelled
CI / Frontend (tsc + vite build) (push) Has been cancelled

- 只翻注释/文档字符串:剥离注释后代码行逐字节不变(机械校验只剩允许的行尾注释形态)
- 裁决编号与 design 节号(02.4.3 / 11.4.2 / design/05 §9 等)逐字保留
- 复核:go build 绿;orchestration 及其子包(audit/comm)测试绿;gofmt 干净
This commit is contained in:
AskaEth committed 2026-10-04 13:30:04 +08:00
1 parent fe90f64a56
commit eb1828ee7a
29 files changed
+751 -949

No files matched your search

@@ -11,43 +11,40 @@ import (
"git.yeij.top/AskaEth/Cyrene_v2/internal/logger"
)
// Sentinel errors returned by Approver. Use errors.Is to test for them.
// Approver 返回的哨兵错误。用 errors.Is 判断它们。
var (
// ErrActionMissing is returned when the action is blank.
// ErrActionMissing 在 action 为空时返回。
ErrActionMissing = errors.New("audit: action is missing")
// ErrUnknownActor is returned when the acting role name is blank. This
// package has no role registry, so a blank name is the only "unknown" it
// can detect; whether a role is truly authorized is decided upstream.
// ErrUnknownActor 在扮演角色的名字为空时返回。本包没有角色注册表,因此空名字是它
// 唯一能检出的「未知」;某个角色是否真的获授权由上游决定。
ErrUnknownActor = errors.New("audit: actor is unknown")
// ErrExplainMissing is returned when the explanation is blank.
// ErrExplainMissing 在说明为空时返回。
ErrExplainMissing = errors.New("audit: explanation is missing")
)
// reviewerMain is the name recorded for the main agent that performs the review.
// reviewerMain 是执行该审查的主 agent 所记录的名字。
const reviewerMain = "main"
// Approval is the immutable record of a single main-agent review-and-approve of
// a subagent's sensitive action.
// Approval 是对子代理敏感操作的一次主代理代审的不可变记录。
type Approval struct {
// Actor is the acting role name (角色名).
// Actor 是扮演角色的名字(角色名)。
Actor string
// Action is the sensitive action being approved.
// Action 是被批准的敏感操作。
Action string
// Description is the explanation of what the actor wants to do (what the
// action means). It is named Description rather than Explain because the
// Explain method (below) returns the frontend notice.
// Description 是对扮演者想做什么的说明(该操作意味着什么)。它命名为
// Description 而非 Explain,因为 Explain 方法(见下)返回的是前端提示短句。
Description string
// Allowed reports whether the action was granted.
// Allowed 报告该操作是否获准。
Allowed bool
// Reviewer is the main agent that performed the review.
// Reviewer 是执行该审查的主 agent。
Reviewer string
// At is when the review-and-approve happened.
// At 是代审发生的时刻。
At time.Time
}
// Explain returns the short frontend notice describing the review outcome. For
// an allowed action it is "「<actor> 想要干什么,我审查后批准了」"; for a denied
// action it uses "我审查后拒绝了". Actor is interpolated in place of <actor>.
// Explain 返回描述审查结果的前端提示短句。获准时是
// "「<actor> 想要干什么,我审查后批准了」";被拒时用 "我审查后拒绝了"。<actor> 处会
// 代入 Actor。
func (a Approval) Explain() string {
if a.Allowed {
return "「" + a.Actor + " 想要干什么,我审查后批准了」"
@@ -55,26 +52,23 @@ func (a Approval) Explain() string {
return "「" + a.Actor + " 想要干什么,我审查后拒绝了」"
}
// Approver records main-agent review-and-approve events and their audit logs.
// Approver 记录主代理代审事件及其审计日志。
type Approver struct {
log *slog.Logger
}
// NewApprover builds an Approver that writes audit logs through log. The logger
// is tagged with source "orchestration/audit". A nil logger is allowed, making
// the approver record silently (no log output).
// NewApprover 构建一个经 log 写入审计日志的 Approver。该 logger 会被标注来源
// "orchestration/audit"。允许传入 nil logger,此时 approver 静默记录(无日志输出)。
func NewApprover(log *slog.Logger) *Approver {
return &Approver{log: logger.WithSource(log, "orchestration/audit")}
}
// ReviewAndApprove validates the request, checks ctx, writes a structured audit
// log (who / what / when / result), and returns the recorded approval with
// Allowed set to true.
// ReviewAndApprove 校验请求、检查 ctx、写入结构化审计日志(谁 / 什么 / 何时 / 结果),
// 并返回记录下来的 approval,其 Allowed 置为 true。
//
// Whether an action is actually sensitive and whether it should be granted is
// decided by the upper policy layer; this method only records, narrates and
// returns the result model. It returns ErrUnknownActor / ErrActionMissing /
// ErrExplainMissing for blank inputs and wraps ctx.Err() when ctx is canceled.
// 某项操作是否真的敏感、是否应予批准由上层策略决定;本方法只记录、叙述并返回结果模型。
// 入参为空时返回 ErrUnknownActor / ErrActionMissing / ErrExplainMissing,ctx 被取消时
// 包装 ctx.Err()。
func (a *Approver) ReviewAndApprove(ctx context.Context, actor, action, describe string) (*Approval, error) {
if err := validateApproval(actor, action, describe); err != nil {
return nil, err
@@ -94,7 +88,7 @@ func (a *Approver) ReviewAndApprove(ctx context.Context, actor, action, describe
return ap, nil
}
// logAudit writes the structured who/what/when/result audit record.
// logAudit 写入结构化的「谁/什么/何时/结果」审计记录。
func (a *Approver) logAudit(ap *Approval) {
if a.log == nil {
return
@@ -109,7 +103,7 @@ func (a *Approver) logAudit(ap *Approval) {
)
}
// validateApproval rejects blank inputs with the matching sentinel.
// validateApproval 以对应的哨兵错误拒绝空入参。
func validateApproval(actor, action, describe string) error {
if strings.TrimSpace(actor) == "" {
return fmt.Errorf("%w: actor is blank", ErrUnknownActor)